@maccesar/titools 2.2.12 → 2.4.0

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

@@ -8,11 +8,17 @@ 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
@@ -20,14 +26,18 @@ const buffer2 = Ti.createBuffer({ value: 'Hello World' });
 const b1 = Ti.createBuffer({ value: 'Part 1. ' });
 const b2 = Ti.createBuffer({ value: 'Part 2.' });
 
-// Append
+// 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 access (array-like)
-b1[0] = 72; // 'H' character in ASCII
+// 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();
@@ -48,6 +58,18 @@ Ti.Codec.encodeNumber({
 });
 ```
 
+### 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({

package/skills/ti-howtos/references/debugging-profiling.md

@@ -180,11 +180,11 @@ Setup:
 5. Click Record
 
 Key columns:
-| Column                            | What it shows           |
-| --------------------------------- | ----------------------- |
-| Persistent Bytes (Live Bytes)     | Memory currently in use |
-| #Persistent (#Living)             | Active object count     |
-| #Transient (#Transitory)          | Ready to garbage collect |
+| Column                        | What it shows            |
+| ----------------------------- | ------------------------ |
+| Persistent Bytes (Live Bytes) | Memory currently in use  |
+| #Persistent (#Living)         | Active object count      |
+| #Transient (#Transitory)      | Ready to garbage collect |
 
 Identifying leaks:
 1. Filter for `Ti` prefix (Titanium objects)
@@ -348,27 +348,22 @@ SELECT * FROM tablename;
 
 ### Creating emulators
 
-Command line:
+> **⚠️ AVD Manager moved to Android Studio**
+> The legacy `android` CLI (`android create avd`, `android avd`) was removed in Android SDK Tools 25.3. Use Android Studio's built-in **AVD Manager** (Tools → Device Manager) or the command-line `avdmanager` tool instead.
+
+Command line (modern):
 ```bash
-# List available targets
-android list targets
+# List available system images
+sdkmanager --list | grep system-images
 
-# Create AVD
-android create avd -n my_emulator -t 1 -s WVGA800 --abi x86
+# Create AVD with avdmanager
+avdmanager create avd -n my_emulator -k "system-images;android-34;google_apis;x86_64"
 
 # Launch emulator
 emulator -avd my_emulator
 ```
 
-AVD Manager (GUI):
-```bash
-android avd
-```
-
-1. Click New
-2. Enter name, select device/target
-3. Choose x86 ABI if available
-4. Click OK
+Android Studio (GUI): Tools → Device Manager → Create Device.
 
 ### Modifying emulators
 
@@ -378,12 +373,6 @@ Edit `~/.android/avd/<NAME>.avd/config.ini`:
 disk.dataPartition.size=1024m
 ```
 
-Resize emulator:
-1. Close emulator
-2. AVD Manager → Select emulator → Edit
-3. Change resolution
-4. Save
-
 Scale on-the-fly:
 ```bash
 # Get emulator port

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

@@ -143,13 +143,13 @@ mapView.addEventListener('click', (e) => {
 });
 
 // Detect drag state changes
+// e.newState holds the drag state constant; e.annotation holds the annotation object
 mapView.addEventListener('pinchangedragstate', (e) => {
-  if (e.annotation.dragState === MapModule.ANNOTATION_DRAG_STATE_END) {
+  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_DRAG,
-//              ANNOTATION_DRAG_STATE_CANCEL, ANNOTATION_DRAG_STATE_END
+// Drag states: ANNOTATION_DRAG_STATE_START, ANNOTATION_DRAG_STATE_END
 
 // Detect region changes
 mapView.addEventListener('regionchanged', (e) => {

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

@@ -77,6 +77,12 @@ 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).
 
@@ -134,8 +140,9 @@ mapView.addEventListener('click', (e) => {
   }
 });
 
+// e.newState holds the drag state constant; e.annotation holds the annotation object
 mapView.addEventListener('pinchangedragstate', (e) => {
-  if (e.annotation.dragState === MapModule.ANNOTATION_DRAG_STATE_END) {
+  if (e.newState === MapModule.ANNOTATION_DRAG_STATE_END) {
     Ti.API.info(`Dropped at: ${e.annotation.latitude}, ${e.annotation.longitude}`);
   }
 });

package/skills/ti-howtos/references/notification-services.md

@@ -531,7 +531,6 @@ Use `UNMutableNotificationContent` with attachments (images, video, audio).
 
 - Service lifecycle: services may be killed if app is swiped away. For critical notifications, use FCM instead of local services.
 - Notification channels: Android 8.0+ requires notification channels.
-- Limitations: legacy MapView only supports a single map view.
 
 ### iOS
 

package/skills/ti-howtos/references/webpack-build-pipeline.md

@@ -1,5 +1,8 @@
 # Webpack build pipeline
 
+> **⚠️ Appcelerator/Axway era feature**
+> The Webpack pipeline documented here was introduced with Titanium SDK 9.1.0 as part of the Axway AMPLIFY toolchain (`appcd` daemon). Since Axway discontinued Appcelerator, this feature is **not maintained** in the current TiDev CLI (`ti`). If you are using the community TiDev CLI, this pipeline may not be available. Prefer the standard `ti build` pipeline unless your project already uses Webpack.
+
 Webpack integration is an alternative build pipeline starting with Titanium SDK 9.1.0. It is optional. When enabled, Webpack manages asset and code bundling.
 
 ## 1. Key benefits

package/skills/ti-ui/SKILL.md

@@ -11,22 +11,21 @@ A practical guide to Titanium SDK UI. Covers layouts, event handling, animations
 
 ## Project detection
 
-:::info auto-detects titanium projects
-This skill detects Titanium projects and provides UI guidance.
-
-Detection happens automatically. You do not need to run a command.
-
-Titanium project indicator:
-- `tiapp.xml` (required for all Titanium projects)
-
-Applicable to both:
-- Alloy projects (app/ folder structure)
-- Classic projects (Resources/ folder)
-
-Behavior based on detection:
-- Titanium detected: Provide UI guidance for Alloy and Classic, ListView/TableView patterns, and platform differences
-- Not detected: State this is for Titanium projects only and skip UI guidance
-:::
+> **️ℹ️ auto-detects titanium projects**
+> This skill detects Titanium projects and provides UI guidance.
+>
+> Detection happens automatically. You do not need to run a command.
+>
+> Titanium project indicator:
+> - `tiapp.xml` (required for all Titanium projects)
+>
+> Applicable to both:
+> - Alloy projects (app/ folder structure)
+> - Classic projects (Resources/ folder)
+>
+> Behavior based on detection:
+> - Titanium detected: Provide UI guidance for Alloy and Classic, ListView/TableView patterns, and platform differences
+> - Not detected: State this is for Titanium projects only and skip UI guidance
 
 ## Quick reference
 
@@ -65,39 +64,38 @@ Behavior based on detection:
 
 ### Platform-specific properties
 
-:::danger critical: platform-specific properties require modifiers
-Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties without platform modifiers will crash cross-platform compilation.
-
-Example of the damage:
-```javascript
-// Wrong: adds Ti.UI.iOS to an Android build
-const win = Ti.UI.createWindow({
-  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-})
-```
-
-Correct approaches:
-
-Option 1: TSS modifier (Alloy projects):
-```tss
-"#mainWindow[platform=ios]": {
-  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-}
-```
-
-Option 2: Conditional code:
-```javascript
-if (OS_IOS) {
-  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-}
-```
-
-Properties that always require platform modifiers:
-- iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
-- Android: `actionBar` config, any `Ti.UI.Android.*` constant
-
-For platform-specific UI patterns, see [platform-ui-ios.md](references/platform-ui-ios.md) and [platform-ui-android.md](references/platform-ui-android.md).
-:::
+> **🚨 critical: platform-specific properties require modifiers**
+> Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties without platform modifiers will crash cross-platform compilation.
+>
+> Example of the damage:
+> ```javascript
+> // Wrong: adds Ti.UI.iOS to an Android build
+> const win = Ti.UI.createWindow({
+>   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
+> })
+> ```
+>
+> Correct approaches:
+>
+> Option 1: TSS modifier (Alloy projects):
+> ```tss
+> "#mainWindow[platform=ios]": {
+>   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
+> }
+> ```
+>
+> Option 2: Conditional code:
+> ```javascript
+> if (OS_IOS) {
+>   $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
+> }
+> ```
+>
+> Properties that always require platform modifiers:
+> - iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
+> - Android: `actionBar` config, any `Ti.UI.Android.*` constant
+>
+> For platform-specific UI patterns, see [platform-ui-ios.md](references/platform-ui-ios.md) and [platform-ui-android.md](references/platform-ui-android.md).
 
 ### Event management
 - Remove global listeners (`Ti.App`, `Ti.Gesture`, `Ti.Accelerometer`) on pause to save battery.

package/skills/ti-ui/references/application-structures.md

@@ -259,7 +259,8 @@ tabGroup.addTab(Ti.UI.createTab({
 
 tabGroup.open();
 ```
-...
+
+```javascript
 // Window-based app with NavigationWindow (iOS)
 const navWindow = Ti.UI.createNavigationWindow({
   window: Ti.UI.createWindow({
@@ -485,7 +486,7 @@ tabGroup.open();
 
 SplitWindow (iPad):
 ```javascript
-const splitWin = Ti.UI.iOS.createSplitWindow({
+const splitWin = Ti.UI.iPad.createSplitWindow({
   masterView: masterWindow,
   detailView: detailWindow
 });

package/skills/ti-ui/references/orientation.md

@@ -50,12 +50,16 @@ iOS plist iPhone vs iPad keys: You can define separate orientations for iPhone a
 - `UISupportedInterfaceOrientations~ipad` for iPad (default: all four)
 - `UISupportedInterfaceOrientations` applies to both if device-specific keys are absent
 
+The `<activity>` element must include `android:name` and be nested inside `<application>`. Titanium generates the main activity name as `<app-id>.<Appname>Activity`.
+
 ```xml
-<android>
+<android xmlns:android="http://schemas.android.com/apk/res/android">
   <manifest>
-    <activity>
-      <android:screenOrientation="portrait"/>
-    </activity>
+    <application>
+      <activity
+        android:name="com.example.myapp.MyappActivity"
+        android:screenOrientation="portrait"/>
+    </application>
   </manifest>
 </android>
 ```
@@ -111,9 +115,9 @@ Ti.Gesture.addEventListener('orientationchange', (e) => {
     adjustForLandscape();
   }
 
-  // Ti.Gesture helper methods - convenience booleans
-  Ti.API.info(`Is portrait: ${e.source.isPortrait()}`);
-  Ti.API.info(`Is landscape: ${e.source.isLandscape()}`);
+  // Ti.Gesture convenience boolean properties
+  Ti.API.info(`Is portrait: ${e.source.portrait}`);
+  Ti.API.info(`Is landscape: ${e.source.landscape}`);
 });
 ```
 
@@ -252,9 +256,13 @@ iOS (tiapp.xml):
 
 Android (tiapp.xml):
 ```xml
-<android>
+<android xmlns:android="http://schemas.android.com/apk/res/android">
   <manifest>
-    <activity android:screenOrientation="portrait"/>
+    <application>
+      <activity
+        android:name="com.example.myapp.MyappActivity"
+        android:screenOrientation="portrait"/>
+    </application>
   </manifest>
 </android>
 ```

package/skills/ti-ui/references/platform-ui-ios.md

@@ -341,6 +341,69 @@ win2.close();
 win1.navBarHidden = true;
 ```
 
+## Community-Discovered Patterns
+
+### Large Titles + ScrollView: required property triad (iOS)
+
+When using `largeTitleEnabled: true` with a `ScrollView` inside a `NavigationWindow`, three Window properties must be set together. Without all three, the ScrollView content overlaps behind the navigation bar.
+
+```javascript
+const win = Ti.UI.createWindow({
+  title: 'My Screen',
+  largeTitleEnabled: true,
+  largeTitleDisplayMode: Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC,
+  extendEdges: [Ti.UI.EXTEND_EDGE_ALL],
+  autoAdjustScrollViewInsets: true,
+  barColor: '#1e293b',
+  backgroundColor: '#0f172a'
+});
+
+const scrollView = Ti.UI.createScrollView({
+  layout: 'vertical',
+  contentWidth: Ti.UI.FILL,
+  contentHeight: Ti.UI.SIZE
+});
+
+scrollView.add(Ti.UI.createLabel({ text: 'Content here' }));
+win.add(scrollView);
+navWindow.openWindow(win);
+```
+
+| Property | Purpose | What breaks without it |
+|---|---|---|
+| `largeTitleEnabled: true` | Large title that collapses on scroll | No large title behavior |
+| `extendEdges: [Ti.UI.EXTEND_EDGE_ALL]` | Content renders behind bars (blur/translucent effect) | Large title renders with visible delay (empty nav bar gap appears first, then title draws) |
+| `autoAdjustScrollViewInsets: true` | Automatically adjusts ScrollView insets | Content overlaps behind the nav bar |
+
+> **Why all three?** `extendEdges` tells iOS to extend content behind the navigation bar. `autoAdjustScrollViewInsets` tells iOS to compensate by adjusting the ScrollView's content insets so content starts below the bar. Without `extendEdges`, there is nothing to adjust — and the large title renders with a visible delay as iOS cannot calculate the full layout upfront. Without `autoAdjustScrollViewInsets`, the content sits behind the bar. They are interdependent.
+
+`largeTitleDisplayMode` controls collapse behavior:
+- `LARGE_TITLE_DISPLAY_MODE_AUTOMATIC` (default) — inherits from previous window; collapses on scroll
+- `LARGE_TITLE_DISPLAY_MODE_ALWAYS` — title stays large regardless of scroll position
+- `LARGE_TITLE_DISPLAY_MODE_NEVER` — always standard title size
+
+#### Works with both NavigationWindow and TabGroup
+
+On iOS, TabGroup wraps each Tab in an implicit NavigationWindow. The same three properties apply to Windows inside both standalone NavigationWindow and TabGroup Tabs. Child windows opened via `navWindow.openWindow()` or from within a Tab inherit the large title behavior when using `LARGE_TITLE_DISPLAY_MODE_AUTOMATIC`.
+
+#### Recommended: global defaults
+
+Instead of repeating the properties on every Window, set them as global defaults:
+
+```javascript
+// app.tss (Alloy)
+'Window[platform=ios]': {
+  autoAdjustScrollViewInsets: true,
+  extendEdges: [Ti.UI.EXTEND_EDGE_ALL]
+}
+```
+
+Then only add `largeTitleEnabled` and `largeTitleDisplayMode` per-window as needed.
+
+> **Note:** The official docs only document the `largeTitleEnabled` + `extendEdges` pair for RefreshControl flicker prevention. The full triad for ScrollView content positioning is not in official documentation.
+
+See also: [scrolling-views.md](scrolling-views.md) for ScrollView properties and patterns.
+
 ### Toolbar
 
 ```javascript

package/skills/ti-ui/references/scrolling-views.md

@@ -241,3 +241,42 @@ scrollView.addEventListener('scroll', (e) => {
 4. Consider performance with large datasets
 5. Test on real devices; simulator behavior may differ
 6. Use paging controls for ScrollableView to improve UX
+
+## Community-Discovered Patterns
+
+### ScrollView inside NavigationWindow with Large Titles (iOS)
+
+When placing a ScrollView inside a Window managed by NavigationWindow, configure the Window to ensure proper content positioning — especially when using large titles or translucent bars.
+
+Three Window properties must be set together:
+
+| Property | Value | Purpose |
+|---|---|---|
+| `extendEdges` | `[Ti.UI.EXTEND_EDGE_ALL]` | Content extends behind bars (enables blur effect) |
+| `autoAdjustScrollViewInsets` | `true` | iOS adjusts ScrollView insets to avoid overlap |
+| `largeTitleEnabled` | `true` | Enables large title that collapses on scroll |
+
+Without `autoAdjustScrollViewInsets`, the ScrollView content overlaps behind the navigation bar when `extendEdges` is set. Without `extendEdges`, the large title renders with a visible delay as iOS cannot calculate the full layout upfront.
+
+This applies to both standalone NavigationWindow and TabGroup (which wraps each Tab in an implicit NavigationWindow on iOS).
+
+```javascript
+const win = Ti.UI.createWindow({
+  title: 'Feed',
+  largeTitleEnabled: true,
+  extendEdges: [Ti.UI.EXTEND_EDGE_ALL],
+  autoAdjustScrollViewInsets: true
+});
+
+const scroll = Ti.UI.createScrollView({
+  layout: 'vertical',
+  contentWidth: Ti.UI.FILL,
+  contentHeight: Ti.UI.SIZE
+});
+
+// Content starts below the nav bar automatically
+scroll.add(Ti.UI.createView({ height: 200, backgroundColor: 'red' }));
+win.add(scroll);
+```
+
+See [platform-ui-ios.md](platform-ui-ios.md) for the full explanation with `largeTitleDisplayMode` options.