@maccesar/titools 2.2.4 → 2.2.9

package/skills/ti-ui/references/event-handling.md

@@ -1,8 +1,8 @@
-# Event Handling
+# Event handling
 
-## 1. Event Listener Pattern
+## 1. Event listener pattern
 
-### Basic Pattern
+### Basic pattern
 
 ```javascript
 element.addEventListener('event_type', (e) => {
@@ -12,40 +12,40 @@ element.addEventListener('event_type', (e) => {
 });
 ```
 ...
-### Events That Bubble
+### Events that bubble
 
-All user input events defined by `Ti.UI.View` bubble up the view hierarchy: `click`, `dblclick`, `doubletap`, `longclick`, `longpress`, `pinch`, `singletap`, `swipe`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `twofingertap`. The **only** `Ti.UI.View` event that does NOT bubble is `postlayout`.
+All user input events defined by `Ti.UI.View` bubble up the view hierarchy: `click`, `dblclick`, `doubletap`, `longclick`, `longpress`, `pinch`, `singletap`, `swipe`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `twofingertap`. The only `Ti.UI.View` event that does not bubble is `postlayout`.
 
-> **Event synonyms**: `singletap` is a synonym for `click`, and `doubletap` is a synonym for `dblclick`.
+Event synonyms: `singletap` is a synonym for `click`, and `doubletap` is a synonym for `dblclick`.
 
-Events representing view-specific state — such as `focus`, `scroll`, and `postlayout` — do **not** bubble. Only user input events bubble.
+Events that represent view-specific state, such as `focus`, `scroll`, and `postlayout`, do not bubble. Only user input events bubble.
 
-### Bubbling Boundaries
+### Bubbling boundaries
 
-Bubbling stops at these special container boundaries: `Window`, `NavigationWindow`, `SplitWindow`, `Tab`, and `TabGroup`.
+Bubbling stops at these container boundaries: `Window`, `NavigationWindow`, `SplitWindow`, `Tab`, and `TabGroup`.
 
-Note that `TableViewSection` is a logical (non-view) container that still participates in bubbling — events from rows bubble through the section to the `TableView`.
+`TableViewSection` is a logical (non-view) container that still participates in bubbling. Events from rows bubble through the section to the `TableView`.
 
-### Native Event Handling Precedence
+### Native event handling precedence
 
-Event bubbling happens after native event handling. Native UI effects (such as highlighting) have already occurred before any event handler fires.
+Event bubbling happens after native event handling. UI effects like highlighting already happened before handlers run.
 
-### Controlling Event Bubbling
+### Controlling event bubbling
 
 ```javascript
 // Check if event bubbles
 Ti.API.info(`Bubbles: ${e.bubbles}`);
 
-// Stop further bubbling — cancelBubble is always false when an event handler is invoked
+// Stop further bubbling - cancelBubble is always false when an event handler is invoked
 e.cancelBubble = true;
 
 // Prevent view from bubbling to parent
 view.bubbleParent = false;
 ```
 
-> **Note**: Multiple events of different types are treated separately. If the user lifting their finger triggers `touchend`, `singletap`, and `click`, setting `cancelBubble` on one does not affect the others.
+Note: Each event type is handled separately. If the user lifting their finger triggers `touchend`, `singletap`, and `click`, setting `cancelBubble` on one does not affect the others.
 
-### Bubbling Example
+### Bubbling example
 
 ```javascript
 const win = Ti.UI.createWindow({
@@ -79,11 +79,11 @@ container.add(button);
 win.open();
 ```
 
-**Output order**: Button → Container → Window
+Output order: Button -> Container -> Window
 
-## 3. Firing Events
+## 3. Firing events
 
-### Fire Custom Event
+### Fire custom event
 
 ```javascript
 // Fire event without data
@@ -102,7 +102,7 @@ button.addEventListener('customEvent', (e) => {
 });
 ```
 ...
-### Listening to App Events
+### Listening to app events
 
 ```javascript
 // Listen anywhere in app
@@ -112,9 +112,9 @@ Ti.App.addEventListener('db_updated', (e) => {
 });
 ```
 
-### Memory Warning
+### Memory warning
 
-Global event listeners persist for app lifetime, preventing garbage collection:
+Global event listeners persist for the app lifetime and prevent garbage collection:
 
 ```javascript
 // Good: Remove when done
@@ -124,9 +124,9 @@ Ti.App.addEventListener('myEvent', handler);
 Ti.App.removeEventListener('myEvent', handler);
 ```
 
-## 5. Touch Events
+## 5. Touch events
 
-### Touch Event Lifecycle
+### Touch event lifecycle
 
 ```javascript
 view.addEventListener('touchstart', (e) => {
@@ -146,19 +146,19 @@ view.addEventListener('touchcancel', (e) => {
 });
 ```
 
-### Touch Enabled
+### Touch enabled
 
-Views must have `touchEnabled: true` to react to touch events (default is true for most components):
+Views must have `touchEnabled: true` to react to touch events. It is true by default for most components.
 
 ```javascript
 view.touchEnabled = false; // Disable touch for this view
 ```
 
-If a view has `touchEnabled: false`, touch events pass to next view in stack.
+If a view has `touchEnabled: false`, touch events pass to the next view in the stack.
 
-## 6. Named vs Anonymous Functions
+## 6. Named vs anonymous functions
 
-### Anonymous Function (One-time use)
+### Anonymous function (one-time use)
 
 ```javascript
 button.addEventListener('click', function(e) {
@@ -166,7 +166,7 @@ button.addEventListener('click', function(e) {
 });
 ```
 
-### Named Function (Reusable)
+### Named function (reusable)
 
 ```javascript
 function handleClick(e) {
@@ -180,9 +180,9 @@ button2.addEventListener('click', handleClick);
 button1.removeEventListener('click', handleClick);
 ```
 
-## 7. Removing Event Listeners
+## 7. Removing event listeners
 
-### Must Match Function Signature
+### Must match function reference
 
 ```javascript
 function myHandler(e) {
@@ -194,13 +194,13 @@ button.addEventListener('click', myHandler);
 button.removeEventListener('click', myHandler);
 ```
 
-**Important**: Anonymous functions cannot be removed!
+Important: Anonymous functions cannot be removed.
 
-## 8. Android Hardware Button Events
+## 8. Android hardware button events
 
-### Available Events
+### Available events
 
-| Event            | Fired When             |
+| Event            | Fired when             |
 | ---------------- | ---------------------- |
 | `androidback`    | Back button released   |
 | `androidhome`    | Home button released   |
@@ -210,7 +210,7 @@ button.removeEventListener('click', myHandler);
 | `androidvolup`   | Volume-up released     |
 | `androidvoldown` | Volume-down released   |
 
-### Handling Back Button
+### Handling back button
 
 ```javascript
 const win = Ti.UI.createWindow({ backgroundColor: 'white' });
@@ -236,13 +236,13 @@ win.addEventListener('androidback', (e) => {
 });
 ```
 
-### Note: Window Types
+### Note: Window types
 
 Since 3.2.0, all windows are heavyweight by default and you cannot control the type of window created. All windows can receive hardware button events.
 
-## 9. Android Menu
+## 9. Android menu
 
-### Create Options Menu
+### Create options menu
 
 ```javascript
 const activity = Ti.Android.currentActivity;
@@ -276,9 +276,9 @@ activity.onOptionsItemSelected = (e) => {
 };
 ```
 
-## 10. Event Listener Best Practices
+## 10. Event listener best practices
 
-### Define Before Event May Fire
+### Define before the event may fire
 
 ```javascript
 // GOOD: Define before opening
@@ -294,7 +294,7 @@ win.addEventListener('open', function(e) {
 });
 ```
 
-### Global Event Memory Leaks
+### Global event memory leaks
 
 ```javascript
 // BAD: Global listener with local reference
@@ -320,7 +320,7 @@ function init() {
 }
 ```
 
-### Remove Listeners on Window Close
+### Remove listeners on window close
 
 ```javascript
 const win = Ti.UI.createWindow();
@@ -333,16 +333,16 @@ win.addEventListener('close', () => {
 });
 ```
 
-## 11. Special Considerations
+## 11. Special considerations
 
-### Platform-Specific Events
+### Platform-specific events
 
 Some events only work on certain platforms:
 - `pinch` - iOS only
 - `globalPoint` property - iOS only
 - Hardware buttons - Android only
 
-### Shake Event
+### Shake event
 
 The `Ti.Gesture` module enables listening for the `shake` event, which fires when the device detects a shake motion:
 
@@ -352,9 +352,9 @@ Ti.Gesture.addEventListener('shake', (e) => {
 });
 ```
 
-### Event Naming
+### Event naming
 
-**WARNING**: Do NOT use spaces in custom event names (causes issues with libraries like Backbone.js):
+Warning: Do not use spaces in custom event names. It can break libraries like Backbone.js.
 
 ```javascript
 // BAD
@@ -364,7 +364,7 @@ Ti.App.fireEvent('my event');
 Ti.App.fireEvent('my_event');
 ```
 
-### Custom Properties on Events
+### Custom properties on events
 
 ```javascript
 button.whichObj = 'button';
@@ -374,12 +374,12 @@ button.addEventListener('click', function(e) {
 });
 ```
 
-## Best Practices Summary
+## Best practices summary
 
-1. **Use app-level events** for cross-context communication
-2. **Remove global listeners** when no longer needed to prevent memory leaks
-3. **Use named functions** when you might need to remove listeners later
-4. **Understand bubbling** to control event propagation
-5. **Define listeners early** - before events are likely to fire
-6. **Handle Android back button** for custom navigation
-7. **Test touch events** on device - simulator may not support all gestures
+1. Use app-level events for cross-context communication.
+2. Remove global listeners when no longer needed.
+3. Use named functions when you might need to remove listeners later.
+4. Understand bubbling to control event propagation.
+5. Define listeners early, before events are likely to fire.
+6. Handle Android back button for custom navigation.
+7. Test touch events on device. Simulator may not support all gestures.

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

@@ -2,17 +2,17 @@
 
 ## 1. Overview
 
-Titanium supports various gestures beyond simple taps:
-- **Touch Events** - Low-level touch tracking
-- **Swipe** - Left/right drag gestures
-- **Pinch** - Zoom gestures (iOS only)
-- **Long Press** - Extended press gesture
-- **Shake** - Device shake detection
-- **Accelerometer** - Device orientation/movement
+Titanium supports more than simple taps.
+- Touch events for low-level tracking.
+- Swipe for left and right drags.
+- Pinch for zoom (iOS only).
+- Long press for extended presses.
+- Shake for device shake detection.
+- Accelerometer for device orientation and movement.
 
-## 2. Touch Events
+## 2. Touch events
 
-### Touch Lifecycle
+### Touch lifecycle
 
 ```javascript
 const view = Ti.UI.createView({
@@ -37,7 +37,7 @@ view.addEventListener('touchcancel', (e) => {
 });
 ```
 
-### Touch Event Properties
+### Touch event properties
 
 | Property      | Description                              |
 | ------------- | ---------------------------------------- |
@@ -45,13 +45,13 @@ view.addEventListener('touchcancel', (e) => {
 | `y`           | Y coordinate in view's coordinate system |
 | `globalPoint` | Screen coordinates (iOS only)            |
 
-### Android Note
+### Android note
 
-On Android, `longpress` and `swipe` cancel touch events - `touchend` may not fire after `touchstart`.
+On Android, `longpress` and `swipe` cancel touch events. `touchend` may not fire after `touchstart`.
 
-## 3. Swipe Gesture
+## 3. Swipe gesture
 
-### Basic Swipe
+### Basic swipe
 
 ```javascript
 const view = Ti.UI.createView({
@@ -66,7 +66,7 @@ view.addEventListener('swipe', (e) => {
 });
 ```
 
-### Swipe Direction Detection
+### Swipe direction detection
 
 ```javascript
 view.addEventListener('swipe', (e) => {
@@ -89,12 +89,12 @@ view.addEventListener('swipe', (e) => {
 });
 ```
 
-### Swipe vs Scroll
+### Swipe vs scroll
 
-- **Swipe**: Quick flick gesture (left/right mainly)
-- **Scroll**: Sustained drag gesture (up/down mainly)
+- Swipe is a quick flick, usually left or right.
+- Scroll is a sustained drag, usually up or down.
 
-## 4. Pinch Gesture (iOS Only)
+## 4. Pinch gesture (iOS only)
 
 ```javascript
 const view = Ti.UI.createView({
@@ -109,7 +109,7 @@ view.addEventListener('pinch', (e) => {
 });
 ```
 
-### Pinch to Zoom
+### Pinch to zoom
 
 ```javascript
 const imageView = Ti.UI.createImageView({
@@ -125,9 +125,9 @@ imageView.addEventListener('pinch', (e) => {
 });
 ```
 
-## 5. Long Press Gesture
+## 5. Long press gesture
 
-### Basic Long Press
+### Basic long press
 
 ```javascript
 const view = Ti.UI.createView({
@@ -141,9 +141,9 @@ view.addEventListener('longpress', (e) => {
 });
 ```
 
-### Long Press Duration
+### Long press duration
 
-Default long press duration varies by platform. Custom handling:
+Default duration varies by platform. You can roll your own:
 
 ```javascript
 let pressTimer = null;
@@ -171,9 +171,9 @@ view.addEventListener('touchmove', () => {
 });
 ```
 
-### Android Long Press Convention
+### Android long press convention
 
-On Android, long press typically shows context menu:
+On Android, long press usually shows a context menu:
 
 ```javascript
 view.addEventListener('longpress', (e) => {
@@ -193,9 +193,9 @@ view.addEventListener('longpress', (e) => {
 });
 ```
 
-## 6. Shake Gesture
+## 6. Shake gesture
 
-### Detecting Shake
+### Detecting shake
 
 ```javascript
 Ti.Gesture.addEventListener('shake', (e) => {
@@ -206,7 +206,7 @@ Ti.Gesture.addEventListener('shake', (e) => {
 });
 ```
 
-### Shake Example
+### Shake example
 
 ```javascript
 // Use shake to refresh data
@@ -225,15 +225,15 @@ function loadDataFromServer() {
 }
 ```
 
-### Testing Shake
+### Testing shake
 
-- **iOS Simulator**: Hardware > Shake Device
-- **Android Emulator**: Not supported - test on physical device
-- **Physical Device**: Just shake the device
+- iOS Simulator: Hardware > Shake Device
+- Android Emulator: not supported, test on physical device
+- Physical device: shake the device
 
-## 7. Accelerometer as Input
+## 7. Accelerometer as input
 
-### Basic Accelerometer
+### Basic accelerometer
 
 ```javascript
 const labelX = Ti.UI.createLabel({ text: 'X: 0' });
@@ -247,7 +247,7 @@ Ti.Accelerometer.addEventListener('update', (e) => {
 });
 ```
 
-### Accelerometer Properties
+### Accelerometer properties
 
 | Property    | Description         | Range                |
 | ----------- | ------------------- | -------------------- |
@@ -256,7 +256,7 @@ Ti.Accelerometer.addEventListener('update', (e) => {
 | `z`         | Z-axis acceleration | G-force              |
 | `timestamp` | When event occurred | Timestamp            |
 
-### Using Accelerometer for Control
+### Using accelerometer for control
 
 ```javascript
 const sensitivity = 2.0;
@@ -279,9 +279,9 @@ Ti.Accelerometer.addEventListener('update', (e) => {
 });
 ```
 
-### Smoothing Accelerometer Data
+### Smoothing accelerometer data
 
-Accelerometer data is very sensitive. Apply smoothing:
+Accelerometer data is noisy. Smooth it:
 
 ```javascript
 let samples = [];
@@ -305,13 +305,11 @@ Ti.Accelerometer.addEventListener('update', (e) => {
 });
 ```
 
-## 8. Gesture Lifecycle Management
+## 8. Gesture lifecycle management
 
-### Battery Considerations
+### Battery considerations
 
-Global gesture events (`Ti.Gesture`, `Ti.Accelerometer`) keep hardware powered and drain battery.
-
-**Always remove listeners when not needed:**
+Global gesture events (`Ti.Gesture`, `Ti.Accelerometer`) keep hardware powered and drain battery. Remove listeners when not needed.
 
 ```javascript
 let accelerometerAdded = false;
@@ -345,35 +343,35 @@ if (Ti.Platform.osname === 'android') {
 }
 ```
 
-## 9. Platform-Specific Considerations
+## 9. Platform-specific considerations
 
 ### iOS
 
-- **Pinch gesture** fully supported
-- **Simulator shake**: Hardware > Shake Device
-- **More touch events** supported
-- **Smoother gesture recognition**
+- Pinch is fully supported.
+- Simulator shake: Hardware > Shake Device.
+- More touch events are supported.
+- Gesture recognition is smoother.
 
 ### Android
 
-- **Pinch** limited/experimental support
-- **No simulator shake** - must test on device
-- **Long press** for context menus (standard pattern)
-- **Hardware button events** available
+- Pinch support is limited or experimental.
+- No simulator shake. Test on device.
+- Long press opens context menus (standard pattern).
+- Hardware button events are available.
 
-## 10. Best Practices
+## 10. Best practices
 
-1. **Test on physical devices** - Simulators don't support all gestures
-2. **Remove global gesture listeners** when not needed to save battery
-3. **Smooth accelerometer data** - Use averaging/rounding
-4. **Use appropriate gesture for context** - Long press for context menus, swipe for navigation
-5. **Consider accessibility** - Ensure gestures don't conflict with screen readers
-6. **Handle edge cases** - Touch cancel, gesture interruptions
-7. **Provide alternatives** - Not all users can perform all gestures
+1. Test on physical devices. Simulators do not support all gestures.
+2. Remove global gesture listeners when not needed to save battery.
+3. Smooth accelerometer data with averaging.
+4. Use the right gesture for the task. Long press for context menus, swipe for navigation.
+5. Consider accessibility. Make sure gestures do not conflict with screen readers.
+6. Handle edge cases like touch cancel and gesture interruptions.
+7. Provide alternatives. Not all users can perform all gestures.
 
-## 11. Combining Gestures
+## 11. Combining gestures
 
-### Multiple Gesture Types
+### Multiple gesture types
 
 ```javascript
 const view = Ti.UI.createView({
@@ -410,7 +408,7 @@ view.addEventListener('pinch', (e) => {
 });
 ```
 
-### Preventing Gesture Conflicts
+### Preventing gesture conflicts
 
 ```javascript
 let touchStartTime = 0;