@maccesar/titools 2.0.0

package/skills/ti-howtos/references/google-maps-v2.md

@@ -0,0 +1,169 @@
+# Google Maps v2 for Android
+
+Guide for implementing native maps on Android using the `ti.map` module (v2).
+
+## Table of Contents
+
+- [Google Maps v2 for Android](#google-maps-v2-for-android)
+  - [Table of Contents](#table-of-contents)
+  - [1. Initial Configuration](#1-initial-configuration)
+    - [Module Installation](#module-installation)
+    - [Obtaining an API Key (Google Cloud Console)](#obtaining-an-api-key-google-cloud-console)
+      - [Get SHA-1 (Debug)](#get-sha-1-debug)
+    - [Configure tiapp.xml](#configure-tiappxml)
+  - [2. Google Play Services Verification](#2-google-play-services-verification)
+  - [3. Using the Map View](#3-using-the-map-view)
+    - [Basic Creation](#basic-creation)
+    - [Map Types](#map-types)
+  - [4. Advanced Annotations (Pins)](#4-advanced-annotations-pins)
+    - [Available Pin Colors](#available-pin-colors)
+  - [5. Routes (Polylines)](#5-routes-polylines)
+  - [6. Critical Events](#6-critical-events)
+  - [7. Limitations and Troubleshooting](#7-limitations-and-troubleshooting)
+
+---
+
+## 1. Initial Configuration
+
+### Module Installation
+Add the module to your `tiapp.xml`:
+```xml
+<modules>
+    <module platform="android">ti.map</module>
+</modules>
+```
+
+### Obtaining an API Key (Google Cloud Console)
+1. Create a project in the [Google Cloud Console](https://console.cloud.google.com/).
+2. Enable "Maps SDK for Android".
+3. Generate an API Key. You will need the **Application ID** from your `tiapp.xml` and the **SHA-1 fingerprint** from your keystore.
+
+#### Get SHA-1 (Debug)
+```bash
+keytool -list -v -keystore ~/Library/Application\ Support/titanium/mobilesdk/osx/<VERSION>/android/dev_keystore
+```
+*Default password: <empty> (press Enter)*
+
+### Configure tiapp.xml
+Add the API Key in the Android section:
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+    <manifest>
+        <application>
+            <meta-data android:name="com.google.android.maps.v2.API_KEY" android:value="YOUR_API_KEY_HERE"/>
+        </application>
+    </manifest>
+</android>
+```
+
+## 2. Google Play Services Verification
+
+It is mandatory to verify availability before rendering the map:
+
+```javascript
+const MapModule = require('ti.map');
+const rc = MapModule.isGooglePlayServicesAvailable();
+
+switch (rc) {
+    case MapModule.SUCCESS:
+        Ti.API.info('Google Play services is installed.');
+        break;
+    case MapModule.SERVICE_MISSING:
+        alert('Google Play services is missing. Please install it.');
+        break;
+    case MapModule.SERVICE_VERSION_UPDATE_REQUIRED:
+        alert('Google Play services is out of date. Please update.');
+        break;
+    default:
+        alert(`Google Play services error: ${rc}`);
+}
+```
+
+## 3. Using the Map View
+
+### Basic Creation
+```javascript
+const MapModule = require('ti.map');
+const mapView = MapModule.createView({
+    mapType: MapModule.NORMAL_TYPE,
+    userLocation: true,
+    traffic: true, // Show real-time traffic
+    animate: true,
+    region: {
+        latitude: -33.87365,
+        longitude: 151.20689,
+        latitudeDelta: 0.1,
+        longitudeDelta: 0.1
+    }
+});
+```
+
+### Map Types
+- `MapModule.NORMAL_TYPE`: Standard map.
+- `MapModule.SATELLITE_TYPE`: Satellite imagery.
+- `MapModule.TERRAIN_TYPE`: Terrain map.
+- `MapModule.HYBRID_TYPE`: Satellite with labels.
+
+## 4. Advanced Annotations (Pins)
+
+```javascript
+const opera = MapModule.createAnnotation({
+    latitude: -33.8569,
+    longitude: 151.2153,
+    title: 'Sydney Opera House',
+    subtitle: 'NSW, Australia',
+    pincolor: MapModule.ANNOTATION_VIOLET,
+    image: 'custom_pin.png', // Custom image
+    draggable: true, // Allow pin dragging
+    // Complete custom view (replaces the pin)
+    customView: Ti.UI.createLabel({ text: '📍', backgroundColor: 'white' })
+});
+
+mapView.addAnnotation(opera);
+```
+
+### Available Pin Colors
+`ANNOTATION_AZURE`, `BLUE`, `CYAN`, `GREEN`, `MAGENTA`, `ORANGE`, `RED`, `ROSE`, `VIOLET`, `YELLOW`.
+
+## 5. Routes (Polylines)
+
+```javascript
+const route = MapModule.createRoute({
+    width: 5,
+    color: '#f00',
+    points: [
+        { latitude: -33.8569, longitude: 151.2153 },
+        { latitude: -33.8522, longitude: 151.2105 }
+    ]
+});
+
+mapView.addRoute(route);
+```
+
+## 6. Critical Events
+
+```javascript
+// Detect click on annotation or its buttons
+mapView.addEventListener('click', (e) => {
+    if (e.clicksource === 'pin') {
+        Ti.API.info(`Pin clicked: ${e.title}`);
+    }
+});
+
+// Detect drag state changes
+mapView.addEventListener('pinchangedragstate', (e) => {
+    if (e.newState === MapModule.ANNOTATION_DRAG_STATE_END) {
+        Ti.API.info(`New position: ${e.annotation.latitude}`);
+    }
+});
+
+// Detect complete rendering
+mapView.addEventListener('complete', (e) => {
+    Ti.API.info('Map loaded');
+});
+```
+
+## 7. Limitations and Troubleshooting
+- **Single Map:** Android (legacy) only allows one MapView instance per application. v2 allows multiple views.
+- **Blank Map:** Verify the API Key is correct and that `android:anyDensity` is NOT set to true in the manifest if using old resolutions.
+- **Simulator:** Google Maps v2 is NOT compatible with the standard emulator without x86 Google Play Services. Real device testing is recommended.

package/skills/ti-howtos/references/ios-map-kit.md

@@ -0,0 +1,143 @@
+# iOS Map Kit
+
+Guide for implementing native maps on iOS using the `ti.map` module.
+
+## Table of Contents
+
+- [iOS Map Kit](#ios-map-kit)
+  - [Table of Contents](#table-of-contents)
+  - [1. Initial Configuration](#1-initial-configuration)
+    - [Module Installation](#module-installation)
+    - [Location Permissions (Info.plist)](#location-permissions-infoplist)
+  - [2. Using the Map View](#2-using-the-map-view)
+    - [Basic Creation](#basic-creation)
+  - [3. 3D Camera (Perspective)](#3-3d-camera-perspective)
+  - [4. iOS Annotations](#4-ios-annotations)
+    - [System Buttons and Callouts](#system-buttons-and-callouts)
+    - [Center Offset](#center-offset)
+  - [5. Advanced Routes](#5-advanced-routes)
+    - [Overlay Levels](#overlay-levels)
+  - [6. Events](#6-events)
+
+---
+
+## 1. Initial Configuration
+
+### Module Installation
+Add the module to your `tiapp.xml`:
+```xml
+<modules>
+    <module platform="iphone">ti.map</module>
+</modules>
+```
+
+### Location Permissions (Info.plist)
+Add the mandatory usage descriptions in `tiapp.xml`:
+```xml
+<ios>
+    <plist>
+        <dict>
+            <key>NSLocationWhenInUseUsageDescription</key>
+            <string>We need your location to show it on the map.</string>
+            <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+            <string>We need continuous location access for navigation.</string>
+        </dict>
+    </plist>
+</ios>
+```
+
+## 2. Using the Map View
+
+### Basic Creation
+```javascript
+const MapModule = require('ti.map');
+const mapView = MapModule.createView({
+    mapType: MapModule.NORMAL_TYPE,
+    userLocation: true,
+    rotatesEnabled: true, // Allow two-finger rotation
+    region: {
+        latitude: 48.8582,
+        longitude: 2.2945,
+        latitudeDelta: 0.02,
+        longitudeDelta: 0.02
+    }
+});
+```
+
+## 3. 3D Camera (Perspective)
+
+iOS allows tilting and rotating the map programmatically for 3D views.
+
+```javascript
+const myCam = MapModule.createCamera({
+    altitude: 300, // Meters above ground
+    centerCoordinate: { latitude: 48.8582, longitude: 2.2945 },
+    heading: -45, // Angle relative to North
+    pitch: 60     // Tilt angle downward
+});
+
+// Apply camera with animation
+mapView.animateCamera({
+    camera: myCam,
+    curve: Ti.UI.ANIMATION_CURVE_EASE_IN,
+    duration: 1000
+});
+
+// Additional 3D view properties
+mapView.pitchEnabled = true;
+mapView.showsBuildings = true; // 3D Buildings
+```
+
+## 4. iOS Annotations
+
+### System Buttons and Callouts
+iOS allows using native buttons inside the pin's callout (popup window).
+
+```javascript
+const bridge = MapModule.createAnnotation({
+    latitude: -33.8522,
+    longitude: 151.2105,
+    title: 'Harbour Bridge',
+    subtitle: 'Port Jackson',
+    pincolor: MapModule.ANNOTATION_PURPLE,
+    // iOS system buttons in the callout
+    leftButton: Ti.UI.iOS.SystemButton.INFO_DARK,
+    rightButton: Ti.UI.iOS.SystemButton.CONTACT_ADD,
+    canShowCallout: true // Default is true
+});
+
+mapView.addAnnotation(bridge);
+```
+
+### Center Offset
+If using a custom pin image that is not centered:
+```javascript
+const customPin = MapModule.createAnnotation({
+    image: 'flag.png',
+    centerOffset: { x: 10, y: -20 } // Visually moves the pin
+});
+```
+
+## 5. Advanced Routes
+
+### Overlay Levels
+Control if the route goes above labels or above roads.
+```javascript
+const route = MapModule.createRoute({
+    points: [...],
+    color: 'blue',
+    width: 4,
+    // OVERLAY_LEVEL_ABOVE_LABELS or OVERLAY_LEVEL_ABOVE_ROADS
+    level: MapModule.OVERLAY_LEVEL_ABOVE_LABELS
+});
+```
+
+## 6. Events
+Same as Android, but with specialized `clicksource` for system buttons:
+```javascript
+mapView.addEventListener('click', (e) => {
+    if (e.clicksource === 'leftButton' || e.clicksource === 'rightButton') {
+        Ti.API.info('Callout button clicked');
+    }
+});
+```