@maccesar/titools 2.10.0 → 3.1.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/cross-platform-development.md

@@ -1,358 +0,0 @@
-# Cross-platform development
-
-Strategies for building Titanium apps that run on iOS and Android from a single codebase.
-
-## Philosophy
-
-### "Write once, adapt everywhere"
-Titanium is not "write once, run anywhere." It is "write once, adapt everywhere."
-
-Shared (90-100%):
-- Business logic
-- Networking code
-- Database operations
-- Event handling
-- Data models
-
-Different:
-- UI conventions (tab position, navigation)
-- Platform-specific features
-- Hardware capabilities
-- User expectations
-
-### Embrace the platform
-Good apps feel native on each platform:
-
-- iOS: bottom tabs, left navigation buttons, iOS-specific controls
-- Android: top tabs, Menu button (legacy), Action Bar, Material Design
-
-Develop for both platforms from day one. It is much easier than porting later.
-
-### Android platform key concepts
-- Screen sizes: small, normal, large, xlarge (measured in dp). Use density-independent resources.
-- Screen densities: ldpi (~120 dpi), mdpi (~160 dpi), hdpi (~240 dpi), xhdpi (~320 dpi), xxhdpi (~480 dpi), xxxhdpi (~640 dpi)
-- Activities: each heavyweight Window maps to an Android Activity. Titanium manages the Activity lifecycle.
-- Intents: for inter-app and intra-app communication. See `android-platform-deep-dives.md`.
-- Back button: hardware/software back closes the current Window by default. Override with `window.addEventListener('androidback', ...)`.
-
-### iOS platform key concepts
-- Human Interface Guidelines: Apple enforces design standards through App Store review. Follow iOS conventions for navigation, tab bars, and gestures.
-- One-button design: no hardware back or menu buttons. All navigation must be in the UI (NavigationWindow, back buttons).
-- Frameworks: Titanium wraps UIKit, Foundation, MapKit, and other Cocoa Touch frameworks. Use Hyperloop for additional frameworks.
-- Developer account: requires a paid Apple Developer Program membership for device testing and App Store distribution.
-
-## Platform identification
-
-### Platform properties
-
-```javascript
-// Platform name
-Ti.Platform.name          // "iPhone OS", "android", "mobileweb"
-Ti.Platform.osname        // "iphone", "ipad", "android", "mobileweb"
-Ti.Platform.model         // "iPhone 15", "Pixel 8", etc.
-```
-
-### Best practice: cache platform checks
-
-```javascript
-// Create aliases - query once, use many times
-const osname = Ti.Platform.osname;
-const isAndroid = (osname === 'android');
-const isIOS = (osname === 'iphone' || osname === 'ipad');
-const isMobileWeb = (osname === 'mobileweb');
-```
-
-### Anti-pattern: do not assume binary
-
-```javascript
-// BAD: Assumes if not Android, then iOS
-if (osname !== 'android') {
-  // Wrong! Could be mobile web or future platform
-}
-
-// GOOD: Explicit checks
-if (isAndroid) {
-  // Android code
-} else if (isIOS) {
-  // iOS code
-}
-```
-
-## Coding strategies
-
-### 1. Branching (mostly similar code)
-Use when code is 90%+ the same with small differences.
-
-```javascript
-const isAndroid = (Ti.Platform.osname === 'android');
-
-const win = Ti.UI.createWindow({
-  backgroundColor: 'white',
-  // Platform-specific property
-  softInputMode: isAndroid ? Ti.UI.Android.SOFT_INPUT_ADJUST_PAN : null
-});
-```
-
-Tips:
-- Cache platform checks to avoid repeated bridge crossings
-- Group as much code as possible within branches
-- Defer loading to reduce performance impact
-
-### 2. Platform-specific files (mostly different code)
-Use when code differs significantly between platforms.
-
-Structure:
-```
-Resources/
-├── ui.js              // Common code (optional)
-├── android/
-│   └── ui.js          // Android-specific (overrides)
-└── iphone/
-    └── ui.js          // iOS-specific (overrides)
-```
-
-Usage:
-```javascript
-// Will automatically include the specific version
-const ui = require('ui');
-// Loads: /android/ui.js on Android, /iphone/ui.js on iOS
-```
-
-### 3. Execution contexts
-Titanium supports single-context and multi-context apps:
-
-- Single context (recommended): all windows share one JavaScript runtime. Use `require()` for modules and `Alloy.createController()` for views.
-- Multi-context (legacy): `Ti.UI.createWindow({ url: 'other.js' })` creates a separate JavaScript context. Variables are not shared between contexts.
-
-Avoid multi-context apps. Use CommonJS modules and `require()` instead. If you must communicate across contexts, use `Ti.App.fireEvent()` and `Ti.App.addEventListener()`.
-
-Avoid multiple contexts:
-```javascript
-// Creates a new context - variables from app.js are not available
-Ti.UI.createWindow({
-  url: 'window.js' // DO NOT DO THIS
-}).open();
-```
-
-Use instead:
-```javascript
-// Same context - all variables available
-const win = Ti.UI.createWindow({});
-require('window')(win);
-win.open();
-```
-
-## Platform-specific resources
-
-### Resource overrides system
-
-```javascript
-// Automatically uses the platform-specific version
-const image = Ti.UI.createImageView({
-  image: '/images/logo.png' // Will choose the correct file
-});
-```
-
-### Assets (Alloy)
-
-```
-app/
-├── assets/
-│   └── images/
-│       └── logo.png      // Default
-├── assets/
-│   └── android/
-│       └── images/
-│           └── logo.png  // Android
-└── assets/
-    └── iphone/
-        └── images/
-            └── logo.png  // iOS
-```
-
-## 5. Webpack build pipeline (TiSDK 9.1.0+)
-
-Titanium's modern build engine optimizes packaging and allows using npm libraries natively.
-
-### `@` alias
-Use `@` to reference your code root regardless of the current folder depth.
-
-```javascript
-import MyModule from '@/utils/myModule'; // Points to app/lib or src
-```
-
-### npm support
-Install any npm package in the project root and use it directly with `import`.
-
-For more details on optimization, diagnostics, and the build web UI, see `webpack-build-pipeline.md`.
-
-## 6. Internationalization (i18n)
-
-### i18n directory structure
-```
-i18n/
-├── en/
-│   ├── strings.xml      <!-- Default language -->
-│   └── app.xml          <!-- App name localization (Android) -->
-├── es/
-│   ├── strings.xml
-│   └── app.xml
-└── ja/
-    └── strings.xml
-```
-
-Use ISO 639-1 language codes (en, es, ja) and optionally ISO 3166-1 region codes (en-GB, pt-BR).
-
-### strings.xml format
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<resources>
-  <string name="welcome_message">Welcome to my app</string>
-  <string name="login_button">Log In</string>
-</resources>
-```
-
-### Using localized strings
-
-Basic usage:
-```javascript
-// Two equivalent methods
-const str1 = L('welcome_message');
-const str2 = Ti.Locale.getString('welcome_message');
-
-// With a default fallback
-const withDefault = L('missing_key', 'Default text');
-```
-
-In Alloy XML views, use `titleid` instead of `title`:
-```xml
-<Button titleid="login_button" />
-<Label textid="welcome_message" />
-```
-
-String formatting:
-```javascript
-// Simple replacement
-const formatted = String.format(L('format_test'), 'Kevin');
-// Result: "Your name is Kevin"
-
-// Ordered replacement
-const formatted = String.format(L('ordered'), 'Jeff', 'Kevin');
-// Result: "Hi Jeff, my name is Kevin"
-```
-
-### Localizing the app name
-
-iOS (SDK 3.2.0+): set `<key>CFBundleDisplayName</key>` in `i18n/LANG/app.xml`
-
-Android: use `<string name="appname">Mi App</string>` in `i18n/LANG/strings.xml`
-
-### Localizing images and files
-
-Two approaches:
-1. Platform folders: place localized images in `app/assets/iphone/LANG.lproj/` (iOS) or `app/assets/android/images/` with language qualifiers (Android)
-2. Code-based: load different assets based on `Ti.Locale.currentLanguage`
-
-### Date and currency formatting
-
-```javascript
-// Date formatting
-const today = new Date();
-const dateStr = String.formatDate(today, 'long');
-const timeStr = String.formatTime(today, 'short');
-
-// Currency
-const price = String.formatCurrency(1234.56);
-
-// Decimal
-const amount = String.formatDecimal(1234.56);
-```
-
-Warning (Android): `String.formatDate()` may produce incorrect translations or field ordering on some Android versions. Consider using JavaScript `Date` methods as a workaround.
-
-### Testing localizations
-
-iOS:
-1. Settings → General → Language & Region
-2. Change iPhone Language
-3. Confirm and restart device
-
-Android:
-1. Settings → Language & input
-2. Select Language
-
-## Platform-specific APIs
-
-### Example: platform-specific properties
-
-```javascript
-const win = Ti.UI.createWindow({
-  // iOS-specific
-  barColor: isIOS ? '#007AFF' : null,
-  titlePrompt: isIOS ? 'Title' : null,
-
-  // Android-specific
-  softInputMode: isAndroid ? Ti.UI.Android.SOFT_INPUT_ADJUST_PAN : null,
-  exitOnClose: isAndroid ? true : false
-});
-```
-
-## Common cross-platform patterns
-
-### Tab groups
-
-```javascript
-const tabGroup = Ti.UI.createTabGroup();
-
-const tab1 = Ti.UI.createTab({
-  title: 'Tab 1',
-  icon: isIOS ? 'tab1.png' : null, // iOS uses icons
-  window: win1
-});
-
-tabGroup.addTab(tab1);
-tabGroup.open();
-```
-
-### Navigation
-
-```javascript
-if (isIOS) {
-  // iOS: navigation window with back button
-  const nav = Ti.UI.iOS.createNavigationWindow({
-    window: win
-  });
-  nav.open();
-} else if (isAndroid) {
-  // Android: open window, use physical button
-  win.open();
-}
-```
-
-### Platform-specific event handling
-
-```javascript
-if (isAndroid) {
-  // Android: handle physical Back button
-  win.addEventListener('androidback', (e) => {
-    // Custom behavior
-    alert('Back pressed!');
-  });
-}
-```
-
-## Best practices
-
-1. Test early on both platforms. Do not wait until "porting time".
-2. Use Alloy. It provides MVC structure and platform abstraction.
-3. Follow platform conventions. iOS apps should feel like iOS, Android like Android.
-4. Cache platform checks. Store in variables, do not call `Ti.Platform.osname` repeatedly.
-5. Use CommonJS modules. Better code organization and reuse.
-6. Leverage resource overrides. Avoid conditional code for images and assets.
-7. Think cross-platform from the design phase. UI should adapt gracefully.
-
-## Resources
-
-- Alloy Framework - MVC framework for Titanium (see alloy-guides skill)
-- CommonJS Modules - module specification (see coding strategies above)
-- Platform API deep dives - iOS and Android platform-specific features