@maccesar/titools 5.3.0 → 5.4.0

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

@@ -0,0 +1,180 @@
+# Platform conventions
+
+> Where iOS and Android genuinely expect different things, and what to do about each.
+
+- Source: https://titaniumsdk.com/docs/build/ui/platform-conventions
+- Written for Titanium SDK 13.4.0 and later.
+- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
+- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.
+
+---
+
+Titanium gives you one layout system and one API, and most of a screen is the
+same on both platforms. This page is for the places where that stops being
+true - where the platforms differ in *approach* rather than in a property name,
+and where writing one behaviour for both produces an app that feels wrong on
+one of them.
+
+Small differences are noted on the page they belong to. These are the
+structural ones.
+
+## Navigating between screens
+
+**iOS stacks windows.** A `NavigationWindow` owns a stack, pushes a window on
+with `openWindow` and pops it with `closeWindow`, and draws a back button in
+the bar automatically.
+
+**Android stacks activities.** Opening a window starts an activity, the
+hardware or gesture back closes it, and there is no navigation container to
+create.
+
+```js
+const android = Ti.Platform.osname === 'android';
+
+const root = Ti.UI.createWindow({ title: 'List', backgroundColor: 'white' });
+const nav = android ? null : Ti.UI.createNavigationWindow({ window: root });
+
+/** Opens a screen the way the platform expects. The one place that branches. */
+function push(win) {
+  if (nav) {
+    nav.openWindow(win);
+  } else {
+    win.open();
+  }
+}
+
+const open = Ti.UI.createButton({ title: 'Open detail' });
+open.addEventListener('click', () => {
+  push(Ti.UI.createWindow({ title: 'Detail', backgroundColor: 'white' }));
+});
+root.add(open);
+
+(nav ?? root).open();
+```
+
+One `push` rather than a platform check at every call site.
+
+> [!IMPORTANT]
+> `NavigationWindow` exists on Android too, but using it there gives you an
+> iOS-shaped navigation inside an activity, and the system back button then
+> does not do what a user expects. Let Android use its own stack.
+
+## The back button
+
+Android has one and iOS does not. That is a real difference in what a user can
+do, not a styling choice.
+
+```js
+const win = Ti.UI.createWindow({ backgroundColor: 'white' });
+let unsaved = true;
+
+win.addEventListener('androidback', () => {
+  if (!unsaved) {
+    win.close();
+    return;
+  }
+  const ask = Ti.UI.createAlertDialog({
+    message: 'Discard changes?',
+    buttonNames: ['Cancel', 'Discard'],
+    cancel: 0
+  });
+  ask.addEventListener('click', (e) => {
+    if (e.index === 1) {
+      unsaved = false;
+      win.close();
+    }
+  });
+  ask.show();
+});
+
+win.open();
+```
+
+Adding an `androidback` listener replaces the default behaviour, so the window
+no longer closes unless you close it. That is the point of the event, and it is
+also the way to leave a user trapped on a screen if you forget the other
+branch.
+
+The last window closing exits the app on Android. `exitOnClose` on the root
+window controls that.
+
+## Title bars
+
+iOS has a navigation bar owned by the stack; Android has an action bar owned by
+the activity. They take different properties.
+
+| | iOS | Android |
+| --- | --- | --- |
+| Title | `Window.title` | `Window.title` |
+| Custom view | `Window.titleControl` | `ActionBar.customView` |
+| Hide it | `Window.navBarHidden` | `ActionBar.hide()` |
+| Back affordance | Automatic | `ActionBar.displayHomeAsUp` |
+
+`Window.title` is the one that works on both, which is why it is worth
+building screens that need nothing more.
+
+## Tabs
+
+`TabGroup` is the same object on both platforms and lands in different places:
+a bottom tab bar on iOS, and tabs the platform places according to its own
+version on Android. Both are correct for their platform.
+
+The thing not to do is force one. An app with iOS-style bottom tabs on Android
+reads as a port.
+
+The guide recommends three to five tabs as a design choice, rather than an
+API limit.
+
+## Menus and actions
+
+iOS puts secondary actions in the navigation bar or a toolbar. Android has an
+options menu in the action bar's overflow.
+
+There is no shared abstraction over the two. Either put the action somewhere
+that exists on both - a button in the content - or write the platform-specific
+version of each and pick with a check.
+
+## Safe areas and system bars
+
+iOS content runs under the notch and the home indicator unless told otherwise.
+`extendSafeArea` on the window controls it. The released
+[Window API](https://titaniumsdk.com/docs/sdk/13.4.1/Titanium.UI.Window)
+defaults to `true` on iOS and `false` on Android. Set it to `false` when the
+system should lay out content within the safe area; with `true`, position
+content to avoid the system bars and physical obstructions.
+
+Android draws behind the status bar in some themes and not others. Set
+`theme` on the window to choose.
+
+Test both on hardware with a notch or a cutout. A simulator in the default
+device rarely shows the problem.
+
+## Which platform am I on
+
+```js
+if (Ti.Platform.osname === 'android') { /* ... */ }
+```
+
+`Ti.Platform.osname` is `'android'`, `'iphone'` or `'ipad'` - so a test for iOS
+has to accept two values. In Alloy, `OS_IOS` and `OS_ANDROID` are compile-time
+constants and the branch not taken is removed from the build rather than
+evaluated at runtime.
+
+In TSS and XML, a platform attribute does the same:
+
+```xml
+<Alloy>
+  <Window>
+    <Button platform="android" title="Android only" />
+  </Window>
+</Alloy>
+```
+
+Prefer those to a runtime check when the difference is layout rather than
+behaviour: the code for the other platform never ships.
+
+![Two boxed screenshots labelled iOS and Android, one above the other, each showing the detail screen of the same app. On iOS a back chevron labelled Notes sits at the left of the navigation bar, with the title Shopping list centred. On Android a plain left arrow sits at the left of the action bar, with the title beside it rather than centred.](https://titaniumsdk.com/docs/guides/back-affordance.png)
+
+## Next
+
+[Working with data](https://titaniumsdk.com/docs/build/data.md) covers storing things between launches.

package/skills/ti-ui/references/user-interface.md

@@ -0,0 +1,43 @@
+# User interface
+
+> Build screens with Titanium's layout system, lists, icons, and the places the platforms differ.
+
+- Source: https://titaniumsdk.com/docs/build/ui
+- Written for Titanium SDK 13.4.0 and later.
+- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
+- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.
+
+---
+
+A Titanium view is a real native view. `Ti.UI.createButton()` makes a
+`UIButton` on iOS and an `android.widget.Button` on Android, and you get a
+handle to it. Nothing here is drawn by Titanium or approximated in a web view.
+
+What Titanium adds on top is one layout system, shared by both platforms, so a
+screen you describe once positions itself on either. That system is the first
+thing to learn and the thing most new Titanium code gets wrong.
+
+![Two boxed screenshots labelled iOS and Android, side by side, showing the same screen: a heading, a switch, a button and a slider in the same order at the same positions. Each control is drawn in its own platform's style, so the iOS switch is green and its button is plain blue text, while the Android switch is blue and its button is a filled rectangle.](https://titaniumsdk.com/docs/guides/one-codebase.png)
+
+## Start here
+
+[Layout and positioning](layouts-and-positioning.md) is the one to read first. Three
+layout modes, two sizing constants, and a precedence order that explains why a
+view you gave a `height` to ignored your `bottom`.
+
+[Lists and tables](listviews-and-performance.md) covers `ListView` and `TableView`, and
+which of the two to reach for. The short answer is `ListView`.
+
+[Icons and launch screens](icons-and-splash-screens.md) is a
+reference: what sizes each platform wants and where the files go.
+
+[Platform conventions](platform-conventions.md) is for the places
+iOS and Android genuinely diverge, rather than the small differences that fit
+in a note on the page you were already reading.
+
+## The API reference is the other half
+
+These pages explain how the pieces fit together. What every property does, on
+which platform, and since which release is in the
+[Titanium API](https://titaniumsdk.com/docs/sdk.md), which is generated from the SDK itself and is
+complete. When a guide and the reference disagree, the reference is right.

package/skills/alloy-guides/references/VIEWS_WITHOUT_CONTROLLERS.md

@@ -1,102 +0,0 @@
-# Views without Controllers
-
-## Introduction
-
-Views can be created without controllers with an optional style sheet. These views can be used as building blocks to create a GUI. After you have defined your controller-less views, the application can either require in these views using markup or can dynamically generate these views in the controller code.
-
-## XML Markup
-
-In XML markup, use the `Require` tag to add controller-less views into another view. Assign the `src` attribute to the name of the view file minus the `.xml` extension and the `type` to `view`. Define the `id` attribute to access each instance of the controller-less view in the controller.
-
-For instance, a button view could be reused repeatedly in a view-controller to construct a dialog box:
-
-**app/views/foo.xml**
-
-```xml
-<Alloy>
-    <Button id='fooButton'>I am a foo button!</Button>
-</Alloy>
-```
-
-This view can be inserted into another view multiple times:
-
-**app/views/index.xml**
-
-```xml
-<Alloy>
-    <Window layout="vertical">
-        <Require id="button1" src="foo" type="view"/>
-        <Require id="button2" src="foo" type="view"/>
-        <Require id="button3" src="foo" type="view"/>
-    </Window>
-</Alloy>
-```
-
-Then, the controller can use `$.button1`, `$.button2` and `$.button3` to access each instance of the foo view.
-
-## Controller Code
-
-**Starting with Alloy 1.4.0**, you can dynamically create views in the controller code. Each component in the controller-less view needs to be assigned an `id` attribute.
-
-**To create a view without a corresponding controller:**
-
-1. Use the `Alloy.createController()` method to create a controller from the controller-less view.
-2. Use the `updateViews()` method with the created controller. Pass a style dictionary with the `id` of each component as the key and attributes as values.
-3. Use the `getView()` method to retrieve the view.
-4. Use the `add()` method to add the view to a parent component.
-
-> **⚠️ ⚠️ Warning**
-> Unlike other style dictionaries in Alloy, when using the `updateViews()` method, you can only apply styles using IDs. Class and view component styles do not work with this method.
->
-> Using the `Require` or `Widget` elements to include external views in the controller-less view does not work with this procedure — you can include the external views, but the styles cannot be updated with the `updateViews` method.
-
-For example:
-
-**app/views/profile.xml**
-
-```xml
-<Alloy>
-    <View id="container">
-        <ImageView id="picture"/>
-        <Label id="name"/>
-    </View>
-</Alloy>
-```
-
-**app/controllers/index.js**
-
-```javascript
-const profile = Alloy.createController('profile');
-profile.updateViews({
-  "#container" : {
-        layout : "vertical"
-  },
-  "#picture" : {
-        image : "/appicon.png"
-  },
-  "#name" : {
-        text : "Mr. Man"
-  }
-});
-$.index.add(profile.getView());
-
-$.index.open();
-```
-
-**Before Alloy 1.4.0**, to dynamically generate a view:
-
-1. Create a new instance of the controller using `Alloy.createController()`.
-2. Modify the properties directly.
-3. Use `getView()` to retrieve the view.
-4. Use `add()` to add it to a parent.
-
-**app/controllers/index.js** (Alloy < 1.4.0)
-
-```javascript
-const profile = Alloy.createController('profile');
-profile.container.layout = 'vertical';
-profile.picture.image = '/appicon.png';
-profile.name.text = 'Mr. Man';
-$.index.add(profile.getView());
-$.index.open();
-```

package/skills/alloy-howtos/references/custom_tags.md

@@ -1,148 +0,0 @@
-# Creating custom tags in Titanium with Alloy
-
-Custom tags let you create reusable UI components without the overhead of widgets. You can keep controls in a single file under `app/lib`.
-
-## Why use custom tags?
-
-When building cross-platform apps, you often need UI controls (like a web-style checkbox) that do not exist natively. You have three approaches:
-
-1.  **Direct XML/JS:** Copy and paste code into each view. Not reusable and easy to drift.
-2.  **Widgets:** Reusable, but require a folder structure and `dependencies` in `config.json`.
-3.  **Custom tags:** Single file in `app/lib/`, no config dependency, easy to share. They reduce platform-specific code in views.
-
-## Basic setup
-
-1.  Create a file in `app/lib/` (e.g., `checkbox.js`)
-2.  Export a `create<TagName>` function
-3.  Use in XML with the `module` attribute
-
-**view.xml**
-```xml
-<CheckBox module="checkbox" id="termsAccepted"
-    caption="I agree to the terms of use"
-    underline="true"
-    onCaptionClick="doShowTerms"
-    onChange="onCheckChange" />
-```
-The `module` attribute tells Alloy to look in `checkbox.js` for a `createCheckBox` function. Alloy passes the XML/TSS arguments and expects a `Ti.UI.*` component back.
-
-## Robust example: CheckBox
-
-**app/lib/checkbox.js**
-```javascript
-exports.createCheckBox = args => {
-    // Wrapper view for all components
-    const wrapper = Ti.UI.createView({
-        top: args.top || 5,
-        width: Ti.UI.SIZE,
-        height: Ti.UI.SIZE,
-        layout: "horizontal",
-        left: args.left || 20,
-        right: args.right || null,
-        checked: args.checked || false
-    });
-
-    // The box itself
-    const box = Ti.UI.createView({
-        width: 15,
-        height: 15,
-        borderWidth: 1,
-        borderColor: "#02A9F4"
-    });
-
-    // Attributed string for styled caption (e.g. underline)
-    const attr = Ti.UI.createAttributedString({
-        text: args.caption
-    });
-
-    if (args.underline) {
-        attr.applyProperties({
-            attributes: [{
-                type: Ti.UI.ATTRIBUTE_UNDERLINES_STYLE,
-                value: Ti.UI.ATTRIBUTE_UNDERLINE_STYLE_SINGLE,
-                range: [0, args.caption.length]
-            }]
-        });
-    }
-
-    const caption = Ti.UI.createLabel({
-        color: "#000",
-        attributedString: attr,
-        left: 10,
-        text: args.caption,
-        font: { fontSize: 10 }
-    });
-
-    // The tick (using Unicode to avoid assets)
-    const tick = Ti.UI.createLabel({
-        text: "\u2713",
-        left: 1,
-        color: "#02A9F4",
-        font: { fontWeight: "bold" },
-        visible: args.checked || false
-    });
-
-    // Handle clicks
-    caption.addEventListener("click", () => {
-        wrapper.fireEvent("captionClick");
-    });
-
-    box.addEventListener("click", () => {
-        tick.visible = !tick.visible;
-        wrapper.checked = !wrapper.checked;
-        wrapper.fireEvent("change", { checked: wrapper.checked });
-    });
-
-    box.add(tick);
-    wrapper.add(box);
-    wrapper.add(caption);
-
-    return wrapper;
-};
-```
-
-## Global module override
-
-Apply a module to all tags in a view by updating the `Alloy` tag. Alloy checks your file for tag creation overrides before using default implementations:
-
-```xml
-<Alloy module="ui">
-    <Window>
-        <CustomButton />  <!-- Looks for createCustomButton in app/lib/ui.js -->
-        <Label />         <!-- Checks ui.js for createLabel first -->
-    </Window>
-</Alloy>
-```
-This is useful for adding default colors or properties (for example, a black default color for Android Labels) across a project.
-
-## Key points
-
-| Aspect        | Description                                                   |
-| ------------- | ------------------------------------------------------------- |
-| File location | `app/lib/<module_name>.js`                                    |
-| Function name | `create<TagName>` (e.g., `createCheckBox` for `<CheckBox>`)   |
-| Return value  | Must return a `Ti.UI.*` component (View, Button, Label, etc.) |
-| Arguments     | Receives all XML/TSS attributes in a single `args` object     |
-
-## Using Custom Tags Without Alloy XML
-
-You can also use custom tags from plain JavaScript via `require()`:
-
-```javascript
-const checkbox = require("checkbox").createCheckBox({
-    caption: "I agree",
-    underline: true
-});
-win.add(checkbox);
-```
-
-This works because custom tags are standard CommonJS modules. The `module` attribute in XML is a convenience.
-
-## Custom tags vs widgets
-
-| Custom Tags                           | Widgets                                  |
-| ------------------------------------- | ---------------------------------------- |
-| Single file in `app/lib/`             | Separate folder structure                |
-| No `config.json` dependency needed    | Requires `dependencies` in `config.json` |
-| Simpler for single-component controls | Better for complex multi-view components |
-| Easier to share across projects       | More formal packaging                    |

package/skills/ti-guides/references/coding-best-practices.md

@@ -1,149 +0,0 @@
-# Coding best practices
-
-Titanium apps are easiest to maintain when they use a single-context, modular pattern with clear structure and organized resources.
-
-## 1. Scope management
-
-- Avoid global scope. Global variables are not automatically garbage collected and can create naming conflicts.
-- Always use `let` or `const`. The original guide uses `var`, but modern code should not. Omitting declarations places variables in global scope.
-
-## 2. Memory leak prevention
-
-- Listeners on `Ti.App`, `Ti.Geolocation`, and similar globals can leak memory if they reference local objects and are not removed.
-```javascript
-// Anti-pattern
-Ti.App.addEventListener('data:sync', (e) => {
-  localView.text = e.text // localView is now leaked
-})
-```
-- Rule: global events should only handle global objects. Always `removeEventListener` during cleanup.
-
-## 3. Event naming conventions
-
-- Do not use spaces in event names. Spaces can cause issues with Backbone.js and other libraries that split event names on spaces.
-```javascript
-// Wrong - may fire multiple times
-Ti.App.fireEvent('my event')
-
-// Correct - use colon or underscore
-Ti.App.fireEvent('my:event')
-Ti.App.fireEvent('my_event')
-```
-
-## 4. Performance
-
-- Defer script loading. Only `require` modules when you need them.
-
-Defer loading to reduce startup time. Only `require` modules when you need them.
-
-Lazy script loading example:
-```javascript
-// must be loaded at launch
-const WindowOne = require('ui/WindowOne').WindowOne;
-const win1 = new WindowOne();
-win1.open();
-
-win1.addEventListener('click', () => {
-  // load window two JavaScript only when needed
-  const WindowTwo = require('ui/WindowTwo').WindowTwo;
-  const win2 = new WindowTwo();
-  win2.open();
-
-  win2.addEventListener('click', () => {
-    // load window three JavaScript only when needed
-    const WindowThree = require('ui/WindowThree').WindowThree;
-    const win3 = new WindowThree();
-    win3.open();
-  });
-});
-```
-
-- Bridge efficiency: minimize requests for device properties like `Ti.Platform.osname`. Store them in a local variable:
-```javascript
-const isAndroid = (Ti.Platform.osname === 'android')
-if (isAndroid) { /* Android path */ } else { /* iOS path */ }
-```
-- Avoid extending the `Ti` namespace. Three reasons:
-  1. Ti objects are proxies to native OS components — your extensions may conflict with native functionality.
-  2. Arrays stored on the namespace may be immutable; objects may be null unexpectedly.
-  3. There is no guarantee properties persist across SDK versions. Use your own namespace or CommonJS module instead of modifying `Ti`.
-
-## 5. App architecture recommendations
-
-### Modular components with CommonJS (recommended)
-
-Titanium's primary recommended architecture. It uses discrete modules and avoids globals. See `commonjs-advanced.md` for module patterns and path resolution.
-
-MyModule.js:
-```javascript
-// Private variable
-const defaultMessage = "Hello world";
-
-exports.sayHello = (msg) => {
-  Ti.API.info('Hello ' + msg);
-};
-
-exports.helloWorld = () => {
-  Ti.API.info(defaultMessage);
-}
-```
-
-app.js:
-```javascript
-const myModule = require('/MyModule');
-myModule.sayHello('User');
-```
-
-### Namespace with deferred loading (alternative pattern)
-
-If not using CommonJS, you can still defer loading with a namespace:
-
-```javascript
-const someNameSpace = () => {
-  const API = {
-    init() {
-      // create UI or initialize
-    },
-    reset() {
-      // null objects, clean up
-    }
-  }
-  return API
-}
-const ns = new someNameSpace()
-```
-
-### Custom objects as components
-
-Popular for rapid deployment. It uses a namespace hierarchy. This pattern is less efficient than CommonJS modules, and object references can persist after they are no longer needed.
-
-```javascript
-const myapp = {};
-(() => {
-  myapp.ui = {};
-  myapp.ui.createApplicationWindow = () => {
-    const win = Ti.UI.createWindow({ backgroundColor:'white' });
-    return win;
-  };
-})();
-```
-
-### Classical-based patterns
-
-Not recommended. JavaScript is not class-based in the same way, and this approach adds overhead during rapid prototyping.
-
-## 6. Security best practices
-
-- Do not store sensitive data in non-JS files. JavaScript files are minified and obfuscated, but images, JSON, SQLite databases, and other non-JS files are packaged as-is. APK and IPA files are ZIP files that can be extracted.
-```javascript
-// Wrong - API keys visible in app/assets/config.json
-const config = require('assets/config.json')
-
-// Correct - store in code or use secure storage
-const API_KEY = Ti.App.Properties.getString('api_key')
-```
-
-## 7. Multiplatform strategies
-
-- Code branching: use for small differences.
-- Platform files: use `.ios.js` or `.android.js` for major logic differences so code stays readable.