@maccesar/titools 5.2.5 → 5.4.0

package/skills/ti-howtos/references/buffer-codec-streams.md

@@ -1,162 +0,0 @@
-# Buffer, Codec, and streams
-
-Guide to binary data manipulation and data flows in Titanium SDK.
-
-## 1. Titanium.Buffer
-
-Buffers are mutable, resizable containers for bytes (byte arrays).
-
-### Creating buffers
-```javascript
-// Empty buffer (initial length 0)
-const buffer0 = Ti.createBuffer();
-
-// Empty 512-byte buffer
-const buffer1 = Ti.createBuffer({ length: 512 });
-
-// Buffer initialized with a string (UTF-8 by default)
-const buffer2 = Ti.createBuffer({ value: 'Hello World' });
-
-// Buffer initialized with explicit charset
-const buffer3 = Ti.createBuffer({ value: 'Hello World', type: Ti.Codec.CHARSET_UTF16 });
-```
-
-### Common operations
-```javascript
-const b1 = Ti.createBuffer({ value: 'Part 1. ' });
-const b2 = Ti.createBuffer({ value: 'Part 2.' });
-
-// Append (resizes b1)
-b1.append(b2);
-
-// Insert at position (resizes buffer as needed)
-const extra = Ti.createBuffer({ value: 'X' });
-b1.insert(extra, 1); // insert extra at index 1
-
-// Truncate
-b1.length = 10;
-
-// Direct array access — buffer is NOT auto-extended; values must be byte values
-b1[0] = 72; // 'H' (ASCII). b1[100] = 1 would throw if index >= b1.length
-
-// Free memory
-b1.release();
-```
-
-## 2. Titanium.Codec
-
-The Codec module encodes and decodes primitive data (numbers and strings) to and from buffers.
-
-### Encoding numbers
-```javascript
-const buffer = Ti.createBuffer({ length: 8 });
-Ti.Codec.encodeNumber({
-  source: 12345,
-  dest: buffer,
-  type: Ti.Codec.TYPE_INT,
-  byteOrder: Ti.Codec.BIG_ENDIAN
-});
-```
-
-### Encoding strings
-```javascript
-// Encode a string into a buffer; returns the byte length written
-const buffer = Ti.createBuffer({ length: 1024 });
-const encodedLength = Ti.Codec.encodeString({
-  source: 'hello world',
-  dest: buffer
-});
-// Trim buffer to actual content
-buffer.length = encodedLength;
-```
-
-### Decoding strings
-```javascript
-const text = Ti.Codec.decodeString({
-  source: buffer,
-  charset: Ti.Codec.CHARSET_UTF8
-});
-```
-
-### Supported types and charsets
-
-Numeric types: `TYPE_BYTE`, `TYPE_SHORT`, `TYPE_INT`, `TYPE_LONG`, `TYPE_FLOAT`, `TYPE_DOUBLE`
-
-String charsets: `CHARSET_UTF8`, `CHARSET_UTF16`, `CHARSET_UTF16BE`, `CHARSET_UTF16LE`, `CHARSET_ISO_LATIN1`
-
-### Position parameter
-The `position` parameter controls where encoding or decoding starts in the buffer:
-```javascript
-Ti.Codec.encodeNumber({
-  source: 42,
-  dest: buffer,
-  position: 4, // start writing at byte 4
-  type: Ti.Codec.TYPE_INT
-});
-```
-
-## 3. Streams
-
-Streams let you read and write data in a serialized, memory-efficient way.
-
-### Stream types
-1. BufferStream: for reading and writing in-memory buffers
-2. FileStream: for file operations (more efficient than `file.read()`)
-3. BlobStream: read-only for Blob objects (images, camera)
-
-Stream modes: `Ti.Filesystem.MODE_READ`, `Ti.Filesystem.MODE_WRITE`, `Ti.Filesystem.MODE_APPEND`
-
-### Example: BufferStream
-```javascript
-const buffer = Ti.createBuffer({ length: 1024 });
-const stream = Ti.Stream.createStream({
-  source: buffer,
-  mode: Ti.Stream.MODE_WRITE
-});
-
-stream.write(Ti.createBuffer({ value: 'Stream data' }));
-stream.close();
-```
-
-### Example: FileStream (chunk-based reading)
-```javascript
-const file = Ti.Filesystem.getFile('large_file.txt');
-const instream = file.open(Ti.Filesystem.MODE_READ);
-const buffer = Ti.createBuffer({ length: 1024 }); // 1KB chunks
-
-let bytesRead = 0;
-while ((bytesRead = instream.read(buffer)) > 0) {
-  Ti.API.info(`Read ${bytesRead} bytes`);
-  // Process buffer...
-}
-instream.close();
-```
-
-### Example: BlobStream (camera to file)
-```javascript
-Ti.Media.showCamera({
-  success: (e) => {
-    const instream = Ti.Stream.createStream({
-      source: e.media,
-      mode: Ti.Stream.MODE_READ
-    });
-
-    const outfile = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, 'photo.jpg');
-    const outstream = outfile.open(Ti.Filesystem.MODE_WRITE);
-
-    const buffer = Ti.createBuffer({ length: 4096 });
-    let readBytes = 0;
-    while ((readBytes = instream.read(buffer)) > 0) {
-      outstream.write(buffer, 0, readBytes);
-    }
-
-    instream.close();
-    outstream.close();
-  }
-});
-```
-
-## 4. Best practices
-- Always close streams to avoid memory leaks and file locks.
-- Use chunks for large files or networking (for example, 1KB or 4KB) to avoid saturating RAM.
-- Buffers vs Blobs: Buffers are mutable; Blobs are immutable. Convert a Blob to a Buffer if you need to modify bytes.

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

@@ -1,172 +0,0 @@
-# Google Maps v2 for Android
-
-Guide to implementing native maps on Android using the `ti.map` module (v2).
-
-## 1. Initial configuration
-
-### Module installation
-Add the module to `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.
-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
-
-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;
-}
-```
-
-## 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: '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}` 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`.
-
-### 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
-// e.newState holds the drag state constant; e.annotation holds the annotation object
-mapView.addEventListener('pinchangedragstate', (e) => {
-  if (e.newState === 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_END
-
-// Detect region changes
-mapView.addEventListener('regionchanged', (e) => {
-  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');
-});
-```
-
-## 7. Migration from legacy Titanium.Map
-
-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 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,149 +0,0 @@
-# iOS Map Kit
-
-Guide to implementing native maps on iOS with the `ti.map` module.
-
-## 1. Initial configuration
-
-### Module installation
-Add the module to `tiapp.xml`:
-
-```xml
-<modules>
-    <module platform="iphone">ti.map</module>
-</modules>
-```
-
-### Location permissions (Info.plist)
-Add the required 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>
-```
-
-iOS 11+: include both `NSLocationWhenInUseUsageDescription` and `NSLocationAlwaysAndWhenInUseUsageDescription`. Users can still choose "When in Use" even if you request "Always".
-
-## 2. Using the map view
-
-### 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
-  }
-});
-```
-
-## 3. 3D camera (perspective)
-
-iOS lets you tilt and rotate the map for 3D views.
-
-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
-});
-
-// 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
-
-### iOS pin colors
-iOS supports only three pin color constants (unlike Android's ten):
-- `MapModule.ANNOTATION_GREEN`
-- `MapModule.ANNOTATION_PURPLE`
-- `MapModule.ANNOTATION_RED`
-
-### 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)
-});
-
-mapView.addAnnotation(bridge);
-```
-
-### 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
-});
-```
-
-## 5. Advanced routes
-
-### Overlay levels
-Control whether the route appears 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)
-});
-```
-
-## 6. Events
-
-Key map events: `click`, `complete` (map loaded), `regionchanged`, `pinchangedragstate`.
-
-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');
-  }
-});
-
-// e.newState holds the drag state constant; e.annotation holds the annotation object
-mapView.addEventListener('pinchangedragstate', (e) => {
-  if (e.newState === MapModule.ANNOTATION_DRAG_STATE_END) {
-    Ti.API.info(`Dropped at: ${e.annotation.latitude}, ${e.annotation.longitude}`);
-  }
-});
-```