@maccesar/titools 2.2.4 → 2.2.8

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

@@ -1,30 +1,32 @@
 # Google Maps v2 for Android
 
-Guide for implementing native maps on Android using the `ti.map` module (v2).
+Guide to implementing native maps on Android using the `ti.map` module (v2).
 
-## 1. Initial Configuration
+## 1. Initial configuration
+
+### Module installation
+Add the module to `tiapp.xml`:
 
-### 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/).
+### Obtaining an API key (Google Cloud Console)
+1. Create a project in the Google Cloud Console.
 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.
+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)
+#### Get SHA-1 (debug)
 ```bash
 keytool -list -v -keystore ~/Library/Application\ Support/titanium/mobilesdk/osx/<VERSION>/android/dev_keystore
 ```
-*Default password: <empty> (press Enter)*
+Default password: empty (press Enter).
 
 ### Configure tiapp.xml
-Add the API Key in the Android section:
+Add the API key in the Android section:
+
 ```xml
 <android xmlns:android="http://schemas.android.com/apk/res/android">
     <manifest>
@@ -35,136 +37,136 @@ Add the API Key in the Android section:
 </android>
 ```
 
-## 2. Google Play Services Verification
+## 2. Google Play Services verification
 
-It is mandatory to verify availability before rendering the map:
+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 available');
-        break;
-    case MapModule.SERVICE_MISSING:
-        Ti.API.error('Google Play Services is missing');
-        break;
-    case MapModule.SERVICE_VERSION_UPDATE_REQUIRED:
-        Ti.API.error('Google Play Services needs update');
-        break;
-    case MapModule.SERVICE_DISABLED:
-        Ti.API.error('Google Play Services is disabled');
-        break;
-    case MapModule.SERVICE_INVALID:
-        Ti.API.error('Google Play Services is invalid');
-        break;
+  case MapModule.SUCCESS:
+    Ti.API.info('Google Play Services available');
+    break;
+  case MapModule.SERVICE_MISSING:
+    Ti.API.error('Google Play Services is missing');
+    break;
+  case MapModule.SERVICE_VERSION_UPDATE_REQUIRED:
+    Ti.API.error('Google Play Services needs update');
+    break;
+  case MapModule.SERVICE_DISABLED:
+    Ti.API.error('Google Play Services is disabled');
+    break;
+  case MapModule.SERVICE_INVALID:
+    Ti.API.error('Google Play Services is invalid');
+    break;
 }
 ```
 
-## 3. Using the Map View
+## 3. Using the map view
 
-### Basic Creation
+### 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
-    }
+  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.
+### 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)
+## 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' })
+  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: 'Pin', backgroundColor: 'white' })
 });
 
 mapView.addAnnotation(opera);
 ```
 
-### Additional Annotation Properties
-- `customView` — a `Ti.UI.View` that replaces the entire annotation (takes precedence over `image`)
-- `centerOffset` — `{x, y}` point to offset the annotation from the coordinate
-- `canShowCallout` — whether tapping shows the info bubble (default: `true`)
+### Additional annotation properties
+- `customView`: a `Ti.UI.View` that replaces the entire annotation (takes precedence over `image`)
+- `centerOffset`: `{x, y}` offset for the annotation relative to the coordinate
+- `canShowCallout`: whether tapping shows the info bubble (default: `true`)
 
-> **Precedence**: `customView` > `image` > default pin. For buttons: `leftView`/`rightView` take precedence over `leftButton`/`rightButton`.
+Precedence: `customView` > `image` > default pin. For buttons: `leftView`/`rightView` take precedence over `leftButton`/`rightButton`.
 
-### Available Pin Colors
+### Available pin colors
 `ANNOTATION_AZURE`, `BLUE`, `CYAN`, `GREEN`, `MAGENTA`, `ORANGE`, `RED`, `ROSE`, `VIOLET`, `YELLOW`.
 
-## 5. Routes (Polylines)
+## 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 }
-    ]
+  width: 5,
+  color: '#f00',
+  points: [
+    { latitude: -33.8569, longitude: 151.2153 },
+    { latitude: -33.8522, longitude: 151.2105 }
+  ]
 });
 
 mapView.addRoute(route);
 ```
 
-## 6. Critical Events
+## 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}`);
-    }
+  if (e.clicksource === 'pin') {
+    Ti.API.info(`Pin clicked: ${e.title}`);
+  }
 });
 
 // Detect drag state changes
 mapView.addEventListener('pinchangedragstate', (e) => {
-    if (e.annotation.dragState === MapModule.ANNOTATION_DRAG_STATE_END) {
-        Ti.API.info(`Dropped at: ${e.annotation.latitude}, ${e.annotation.longitude}`);
-    }
+  if (e.annotation.dragState === MapModule.ANNOTATION_DRAG_STATE_END) {
+    Ti.API.info(`Dropped at: ${e.annotation.latitude}, ${e.annotation.longitude}`);
+  }
 });
 // Drag states: ANNOTATION_DRAG_STATE_START, ANNOTATION_DRAG_STATE_DRAG,
 //              ANNOTATION_DRAG_STATE_CANCEL, ANNOTATION_DRAG_STATE_END
 
 // Detect region changes
 mapView.addEventListener('regionchanged', (e) => {
-    Ti.API.info(`New region: ${e.latitude}, ${e.longitude} (delta: ${e.latitudeDelta}, ${e.longitudeDelta})`);
+  Ti.API.info(`New region: ${e.latitude}, ${e.longitude} (delta: ${e.latitudeDelta}, ${e.longitudeDelta})`);
 });
 
 // Detect complete rendering
 mapView.addEventListener('complete', (e) => {
-    Ti.API.info('Map loaded');
+  Ti.API.info('Map loaded');
 });
 ```
 
-## 7. Migration from Legacy Titanium.Map
+## 7. Migration from legacy Titanium.Map
 
-> **Note**: The `ti.map` module replaced the legacy `Titanium.Map` API. Key differences: use `NORMAL_TYPE` instead of `STANDARD_TYPE`, `ANNOTATION_VIOLET` instead of `ANNOTATION_PURPLE`, and routes are created with `Map.createRoute()` instead of abstract data types. Multiple MapView instances are supported.
+The `ti.map` module replaced the legacy `Titanium.Map` API. Key differences: use `NORMAL_TYPE` instead of `STANDARD_TYPE`, `ANNOTATION_VIOLET` instead of `ANNOTATION_PURPLE`, and routes are created with `Map.createRoute()` instead of abstract data types. Multiple MapView instances are supported.
 
-## 8. 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.
+## 8. Limitations and troubleshooting
+- Single map: Android (legacy) only allows one MapView instance per application. v2 allows multiple views.
+- Blank map: verify the API key and make sure `android:anyDensity` is not set to true in the manifest if you use old resolutions.
+- Simulator: Google Maps v2 is not compatible with the standard emulator without x86 Google Play Services. Test on a real device.

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

@@ -1,19 +1,21 @@
 # iOS Map Kit
 
-Guide for implementing native maps on iOS using the `ti.map` module.
+Guide to implementing native maps on iOS with the `ti.map` module.
 
-## 1. Initial Configuration
+## 1. Initial configuration
+
+### Module installation
+Add the module to `tiapp.xml`:
 
-### 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`:
+### Location permissions (Info.plist)
+Add the required usage descriptions in `tiapp.xml`:
+
 ```xml
 <ios>
     <plist>
@@ -27,93 +29,95 @@ Add the mandatory usage descriptions in `tiapp.xml`:
 </ios>
 ```
 
-> **iOS 11+**: You must include both `NSLocationWhenInUseUsageDescription` AND `NSLocationAlwaysAndWhenInUseUsageDescription` in your plist. Users can choose "When in Use" even when your app requests "Always" authorization.
+iOS 11+: include both `NSLocationWhenInUseUsageDescription` and `NSLocationAlwaysAndWhenInUseUsageDescription`. Users can still choose "When in Use" even if you request "Always".
 
-## 2. Using the Map View
+## 2. Using the map view
 
-### Basic Creation
+### Basic creation
 ```javascript
 const MapModule = require('ti.map');
 const mapView = MapModule.createView({
-    mapType: MapModule.NORMAL_TYPE, // Also: SATELLITE_TYPE, HYBRID_TYPE, STANDARD_TYPE (alias for NORMAL_TYPE with labels)
-    userLocation: true,
-    rotatesEnabled: true, // Allow two-finger rotation
-    region: {
-        latitude: 48.8582,
-        longitude: 2.2945,
-        latitudeDelta: 0.02,
-        longitudeDelta: 0.02
-    }
+  mapType: MapModule.NORMAL_TYPE, // Also: SATELLITE_TYPE, HYBRID_TYPE, STANDARD_TYPE (alias for NORMAL_TYPE with labels)
+  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)
+## 3. 3D camera (perspective)
 
-iOS allows tilting and rotating the map programmatically for 3D views.
+iOS lets you tilt and rotate the map for 3D views.
 
-> **Important**: The map view must be visible on screen before using camera APIs. Wait for the map's `complete` event before calling `animateCamera()` or setting camera properties.
+Important: the map must be visible on screen before using camera APIs. Wait for the `complete` event before calling `animateCamera()` or setting camera properties.
 
 ```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
+  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
+  camera: myCam,
+  curve: Ti.UI.ANIMATION_CURVE_EASE_IN,
+  duration: 1000
 });
 
 // Additional 3D view properties
 mapView.pitchEnabled = true;
-mapView.showsBuildings = true; // 3D Buildings
+mapView.showsBuildings = true; // 3D buildings
 ```
 
-## 4. iOS Annotations
+## 4. iOS annotations
 
-### System Buttons and Callouts
-iOS allows using native buttons inside the pin's callout (popup window).
+### System buttons and callouts
+iOS allows native buttons in the pin 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 // Controls whether tapping the annotation shows the callout bubble (default: true)
+  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 // Controls whether tapping the annotation shows the callout bubble (default: true)
 });
 
 mapView.addAnnotation(bridge);
 ```
 
-### Center Offset
-If using a custom pin image that is not centered:
+### Center offset
+If you use 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
+  image: 'flag.png',
+  centerOffset: { x: 10, y: -20 } // Visually moves the pin
 });
 ```
 
-## 5. Advanced Routes
+## 5. Advanced routes
+
+### Overlay levels
+Control whether the route appears above labels or above roads.
 
-### Overlay Levels
-Control if the route goes above labels or above roads.
 ```javascript
 const route = MapModule.createRoute({
-    points: routePoints,
-    color: '#00f',
-    width: 4,
-    level: MapModule.OVERLAY_LEVEL_ABOVE_LABELS  // default
-    // or MapModule.OVERLAY_LEVEL_ABOVE_ROADS (below labels)
+  points: routePoints,
+  color: '#00f',
+  width: 4,
+  level: MapModule.OVERLAY_LEVEL_ABOVE_LABELS // default
+  // or MapModule.OVERLAY_LEVEL_ABOVE_ROADS (below labels)
 });
 ```
 
@@ -121,17 +125,18 @@ const route = MapModule.createRoute({
 
 Key map events: `click`, `complete` (map loaded), `regionchanged`, `pinchangedragstate`.
 
-Same as Android, but with specialized `clicksource` for system buttons:
+Same as Android, but with specialized `clicksource` values for system buttons:
+
 ```javascript
 mapView.addEventListener('click', (e) => {
-    if (e.clicksource === 'leftButton' || e.clicksource === 'rightButton') {
-        Ti.API.info('Callout button clicked');
-    }
+  if (e.clicksource === 'leftButton' || e.clicksource === 'rightButton') {
+    Ti.API.info('Callout button clicked');
+  }
 });
 
 mapView.addEventListener('pinchangedragstate', (e) => {
-    if (e.annotation.dragState === MapModule.ANNOTATION_DRAG_STATE_END) {
-        Ti.API.info(`Dropped at: ${e.annotation.latitude}, ${e.annotation.longitude}`);
-    }
+  if (e.annotation.dragState === MapModule.ANNOTATION_DRAG_STATE_END) {
+    Ti.API.info(`Dropped at: ${e.annotation.latitude}, ${e.annotation.longitude}`);
+  }
 });
 ```