@maccesar/titools 2.2.3 → 2.2.8

package/skills/ti-guides/references/hyperloop-native-access.md

@@ -1,14 +1,14 @@
-# Hyperloop: Native API Access
+# Hyperloop: native API access
 
-Hyperloop allows you to access 100% of native APIs (iOS Objective-C/Swift and Android Java/Kotlin) directly from JavaScript. It is pre-packaged with the Titanium SDK and works as a native module.
+Hyperloop lets you access native APIs (iOS Objective-C/Swift and Android Java/Kotlin) directly from JavaScript. It ships with the Titanium SDK and works as a native module.
 
 ## 1. Requirements
 
-- **Titanium SDK**: 9.0.0+
-- **Titanium CLI**: 7.0.0+
-- **Alloy** (optional): 1.8.0+
-- **CocoaPods** (optional, iOS only): 1.0.0+
-- **Xcode location**: Must be at `/Applications/Xcode.app` -- Hyperloop uses a bundled library from Xcode to inspect available native APIs. Having Xcode in a non-default location (via `xcode-select` or Xcode preferences) while another installation exists in the default folder can cause metadata errors.
+- Titanium SDK: 9.0.0+
+- Titanium CLI: 7.0.0+
+- Alloy (optional): 1.8.0+
+- CocoaPods (optional, iOS only): 1.0.0+
+- Xcode location: must be at `/Applications/Xcode.app`. Hyperloop uses a bundled Xcode library to inspect native APIs. If Xcode is in a non-default location while another installation exists in the default folder, metadata errors can occur.
 
 ## 2. Enabling Hyperloop
 
@@ -25,20 +25,20 @@ The `run-on-main-thread` property should already be in `tiapp.xml` by default:
 <property name="run-on-main-thread" type="bool">true</property>
 ```
 
-> Do NOT name your app "Hyperloop" in tiapp.xml -- it is a reserved word and will cause build failures.
+Do not name your app "Hyperloop" in `tiapp.xml`. It is a reserved word and will cause build failures.
 
-## 3. Framework Namespace Conventions
+## 3. Framework namespace conventions
 
-Each platform uses different `require()` conventions:
+Each platform uses different `require()` conventions.
 
-**iOS** -- use `Framework/Class` with a forward slash:
+iOS: use `Framework/Class` with a forward slash:
 ```javascript
 const UIView = require('UIKit/UIView');
 const NSBundle = require('Foundation/NSBundle');
 const UIColor = require('UIKit/UIColor');
 ```
 
-**Android** -- use the full Java package with dots:
+Android: use the full Java package with dots:
 ```javascript
 const View = require('android.view.View');
 const Activity = require('android.app.Activity');
@@ -49,8 +49,8 @@ const Context = require('android.content.Context');
 
 ### Instantiation: `new` vs `alloc().init()`
 
-- **`new Class()`**: Equivalent to `alloc().init()`. Only calls the **default** initializer (`init`).
-- **`Class.alloc().initWith*()`**: Use when you need a **special initializer** with arguments.
+- `new Class()` is equivalent to `alloc().init()`. It only calls the default initializer (`init`).
+- `Class.alloc().initWith*()` is for special initializers that take arguments.
 
 ```javascript
 const UIView = require('UIKit/UIView');
@@ -59,12 +59,12 @@ const UIView = require('UIKit/UIView');
 const view1 = new UIView();
 const view2 = UIView.alloc().init();
 
-// Special initializer with arguments -- must use alloc().init*()
+// Special initializer with arguments
 const CGRectMake = require('CoreGraphics').CGRectMake;
 const view3 = UIView.alloc().initWithFrame(CGRectMake(0, 0, 100, 100));
 ```
 
-### Named Methods (Selector Concatenation)
+### Named methods (selector concatenation)
 
 Selectors with multiple parameters are camel-cased and colons are removed. Arguments are passed in the same order as in Objective-C.
 
@@ -84,7 +84,7 @@ UIView.animateWithDurationAnimationsCompletion(1.0, () => {
 
 ### Properties
 
-Objective-C properties map directly to JavaScript property accessors. Auto-generated setters are also available:
+Objective-C properties map to JavaScript property accessors. Auto-generated setters are also available:
 ```javascript
 view.backgroundColor = UIColor.redColor;
 // or
@@ -105,7 +105,7 @@ const tiView = Ti.UI.createView({ backgroundColor: 'red' });
 const nativeView = UIView.cast(tiView);
 ```
 
-> Be careful with casting: casting to the wrong type will cause a crash.
+Be careful with casting. Casting to the wrong type can crash.
 
 ### Blocks
 
@@ -120,7 +120,7 @@ UIView.animateWithDurationAnimationsCompletion(1.0, () => {
 });
 ```
 
-### Constants, Enumerations, and Functions
+### Constants, enumerations, and functions
 
 Framework-level constants and enums are accessed by requiring the framework itself:
 ```javascript
@@ -129,7 +129,7 @@ const unspecified = UIKit.UISemanticContentAttributeUnspecified;
 view.semanticContentAttribute = unspecified;
 ```
 
-### TiApp Utility Class
+### TiApp utility class
 
 Access Titanium's app instance for the app delegate, key window, and app-level properties:
 ```javascript
@@ -137,7 +137,7 @@ const TiApp = require('TiApp/TiApp');
 const app = TiApp.app();
 ```
 
-## 5. iOS: Creating Custom Classes
+## 5. iOS: creating custom classes
 
 Use `Hyperloop.defineClass()` to create Objective-C classes at runtime:
 
@@ -172,27 +172,27 @@ MyView.addMethod({
 ```
 
 `addMethod` properties:
-- **`selector`**: The Objective-C selector string
-- **`instance`**: `true` for instance methods, `false` for class methods
-- **`arguments`**: Array or String of argument types (Objective-C encoding types or general types like `float`, `int`, `id`)
-- **`returnType`**: String return type. Omit for `void`.
-- **`callback`**: The JavaScript function implementation
+- `selector`: Objective-C selector string
+- `instance`: `true` for instance methods, `false` for class methods
+- `arguments`: array or string of argument types (Objective-C encoding types or general types like `float`, `int`, `id`)
+- `returnType`: string return type (omit for `void`)
+- `callback`: JavaScript implementation
 
 Instantiate the custom class normally:
 ```javascript
 const myView = new MyView();
 ```
 
-## 6. iOS: CocoaPods Support
+## 6. iOS: CocoaPods support
 
 ### Installation
 
-Install CocoaPods if not already installed:
+Install CocoaPods if needed:
 ```bash
 sudo gem install cocoapods
 ```
 
-### Podfile Configuration
+### Podfile configuration
 
 Create a `Podfile` in your Titanium project root:
 ```ruby
@@ -206,9 +206,9 @@ target 'YourProjectName' do
 end
 ```
 
-Replace `YourProjectName` with your actual Titanium project name.
+Replace `YourProjectName` with your Titanium project name.
 
-### Using the Pod
+### Using the pod
 
 ```javascript
 const JBBarChartView = require('JBChartView/JBBarChartView');
@@ -217,7 +217,7 @@ chart.minimumValue = 1;
 chart.maximumValue = 100;
 ```
 
-### Bitcode Handling for Ad-Hoc Builds
+### Bitcode handling for Ad Hoc builds
 
 If your build fails due to mixed Bitcode frameworks, disable Bitcode in your Podfile:
 ```ruby
@@ -230,11 +230,11 @@ post_install do |installer|
 end
 ```
 
-### Custom Frameworks (without CocoaPods)
+### Custom frameworks (without CocoaPods)
 
-Drop native iOS frameworks (static or dynamic) into `app/platform/ios` (Alloy) or `platform/ios` (Classic). They will be automatically detected and linked.
+Drop native iOS frameworks (static or dynamic) into `app/platform/ios` (Alloy) or `platform/ios` (Classic). They will be detected and linked.
 
-## 7. iOS: Swift Support
+## 7. iOS: Swift support
 
 Hyperloop supports Swift classes alongside Objective-C:
 - Swift and Objective-C classes can be mixed in the same app
@@ -243,7 +243,7 @@ Hyperloop supports Swift classes alongside Objective-C:
 
 ## 8. iOS: XIB and Storyboards
 
-XIB files and Storyboards must be programmatically loaded. Place them in `app/assets/iphone` (Alloy) or `Resources/iphone` (Classic) and they will be compiled automatically.
+XIB files and Storyboards must be loaded programmatically. Place them in `app/assets/iphone` (Alloy) or `Resources/iphone` (Classic) and they will be compiled automatically.
 
 ```javascript
 const NSBundle = require('Foundation/NSBundle');
@@ -255,7 +255,7 @@ const objects = nib.instantiateWithOwnerOptions(null, null);
 
 The following resources are compiled automatically: `*.storyboard`, `*.xcdatamodel`, `*.xcdatamodeld`, `*.xcmappingmodel`, `*.xib`.
 
-## 9. iOS: Customizing the Xcode Build
+## 9. iOS: customizing the Xcode build
 
 Use `appc.js` in the project root to pass custom flags to `xcodebuild`:
 ```javascript
@@ -274,7 +274,7 @@ module.exports = {
 
 ## 10. Android (Java)
 
-### Activity Context
+### Activity context
 
 Most Android view constructors require an Activity context:
 ```javascript
@@ -282,17 +282,17 @@ const Activity = require('android.app.Activity');
 const activity = new Activity(Ti.Android.currentActivity);
 ```
 
-### Methods and Fields
+### Methods and fields
 
 Java methods map to JavaScript functions. Java fields map to JavaScript property accessors. Static methods and constants are attached to the class type:
 ```javascript
 const View = require('android.view.View');
-const generatedId = View.generateViewId(); // static method
+const generatedId = View.generateViewId();
 ```
 
-### Method Overloading
+### Method overloading
 
-Hyperloop automatically selects the matching overload based on parameter types. It is slightly more liberal with numeric primitives due to JavaScript Number conversion.
+Hyperloop selects the matching overload based on parameter types. It is slightly more liberal with numeric primitives because JavaScript numbers are all `Number`.
 
 ### Casting
 
@@ -321,7 +321,7 @@ const listener = new OnTouchListener({
 });
 ```
 
-### Creating Custom Classes (Android)
+### Creating custom classes (Android)
 
 Use `.extend()` on the class to subclass, passing an object with method overrides:
 ```javascript
@@ -338,9 +338,9 @@ const MyView = View.extend({
 const customView = new MyView(activity);
 ```
 
-## 11. Android: Native XML Layouts
+## 11. Android: native XML layouts
 
-### Creating the Layout
+### Creating the layout
 
 Place XML layout files in `app/platform/android/res/layout/` (Alloy) or `platform/android/res/layout/` (Classic).
 
@@ -366,7 +366,7 @@ Example `main_content.xml`:
 </androidx.coordinatorlayout.widget.CoordinatorLayout>
 ```
 
-### Inflating the Layout
+### Inflating the layout
 
 ```javascript
 const Activity = require('android.app.Activity');
@@ -386,15 +386,15 @@ const view = inflater.inflate(resId, null);
 $.myView.add(view);
 ```
 
-`getIdentifier()` also works for other resource types: `R.color.*`, `R.string.*`, `R.drawable.*`, etc.
+`getIdentifier()` also works for other resource types: `R.color.*`, `R.string.*`, `R.drawable.*`, and others.
 
-## 12. Android: Third-Party Libraries
+## 12. Android: third-party libraries
 
-### AndroidX Requirement
+### AndroidX requirement
 
-As of Titanium SDK 9.0.0, you must use **AndroidX** libraries. Google's deprecated Support libraries (`android.support.*`) are no longer supported.
+As of Titanium SDK 9.0.0, you must use AndroidX libraries. The deprecated Support libraries (`android.support.*`) are not supported.
 
-### Gradle Dependencies (Preferred)
+### Gradle dependencies (preferred)
 
 Add a `build.gradle` file to `app/platform/android/` (Alloy) or `platform/android/` (Classic):
 
@@ -404,13 +404,13 @@ dependencies {
 }
 ```
 
-### Local JAR/AAR Dependencies
+### Local JAR/AAR dependencies
 
-Place JAR and AAR files directly in `app/platform/android/` (Alloy) or `platform/android/` (Classic). Hyperloop will automatically:
+Place JAR and AAR files directly in `app/platform/android/` (Alloy) or `platform/android/` (Classic). Hyperloop will:
 - Load Java classes and generate bindings
-- For AARs: extract resources, assets, `*.so` libraries, and merge `AndroidManifest.xml`
+- For AARs, extract resources, assets, `*.so` libraries, and merge `AndroidManifest.xml`
 
-### Third-Party Library Example
+### Third-party library example
 
 ```javascript
 // After adding the AAR to app/platform/android/
@@ -436,20 +436,20 @@ $.myView.add(parkedView);
 
 ## 13. Debugging Hyperloop
 
-- **iOS**: Use **Safari Web Inspector** to debug Hyperloop code up to the native transition point
-- **Android**: Use **Chrome DevTools** for JavaScript debugging
-- Breakpoints may not hit correctly in all cases because Hyperloop modifies source files during the build process
+- iOS: use Safari Web Inspector to debug Hyperloop code up to the native transition point
+- Android: use Chrome DevTools for JavaScript debugging
+- Breakpoints may not hit correctly because Hyperloop modifies source files during the build process
 - No source maps are available for processed Alloy controllers
 
-## 14. Performance Tips
+## 14. Performance tips
 
-- Do NOT use Hyperloop for things Titanium already does well
-- Use it for specialized APIs: custom UI components, hardware access not covered by modules, or native third-party library integration
-- Existing Titanium modules (Java for Android, Objective-C for iOS) continue to be fully supported alongside Hyperloop
+- Do not use Hyperloop for things Titanium already does well.
+- Use it for specialized APIs: custom UI components, hardware access not covered by modules, or native third-party library integration.
+- Existing Titanium modules (Java for Android, Objective-C for iOS) continue to be supported alongside Hyperloop.
 
-## 15. Sample Projects
+## 15. Sample projects
 
-The official cross-platform example app demonstrates native APIs for iOS and Android, including CocoaPods, Android AAR packages, UICollectionView, Beacons, BottomNavigationView, native XML layouts, Storyboards, XIBs, and more:
+The cross-platform example app demonstrates native APIs for iOS and Android, including CocoaPods, Android AAR packages, UICollectionView, Beacons, BottomNavigationView, native XML layouts, Storyboards, XIBs, and more.
 
-- **Repository**: `https://github.com/tidev/hyperloop-examples`
-- **Community modules**: `https://github.com/hyperloop-modules` -- JavaScript wrappers around native APIs (Speech, Mapbox, Snackbar, etc.)
+- Repository: https://github.com/tidev/hyperloop-examples
+- Community modules: https://github.com/hyperloop-modules (JavaScript wrappers around native APIs such as Speech, Mapbox, Snackbar)