Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fixed formatting and broken API links

Table of Contents
maxLevel5
minLevel2

The Titanium API is made up of modules--collections of related methods, properties, and constants. There are several types of modules:

...

  • Packaged modules are optional extensions to the Titanium API that can be imported into your application using the require  method. Packaged modules are imported using an identifier (such as ti.cloud). Packaged modules can include native code, JavaScript, or both. Packaged modules are available from the Appcelerator Marketplace, as well as other sources.

...

This section deals with extending the Titanium API by building packaged modules, which can be sold through the Appcelerator Marketplace or distributed through other means.

Packaged Titanium

...

modules

A packaged module is a module that can contain native code, JavaScript, or both. It is built, or packaged, for a specific platform--at this point, packaged modules are supported on Android, iOS and Mobile Web. When you package a module, any native code is compiled and any JavaScript is obfuscated, so the module can be distributed without sharing your source code.

...

Since packaged modules can contain native code, a module can generally do anything that native code can do. On Mobile Web, of course, JavaScript is the native language of the platform. On Android and iOS, there are a number of special considerations for writing native code, as well as a set of module APIs for integrating with Titanium.

Native

...

modules

To write a native module for Android or iOS, you need to be familiar with several concepts:

...

When you create an instance of a proxy object and return it to the JavaScript layer, the JavaScript engine creates a corresponding JavaScript object. When you call a method on the JavaScript object that's bound to a native method on the proxy object, the JavaScript engine invokes the native method. Likewise, when you access a property on the JavaScript object that's bound to a property on the proxy object, the JavaScript engine invokes a setter or getter for that property. For example, consider the following code:

Code Block
linenumberstrue
languagejs
// 1. Create a proxy object
var win = Ti.UI.createWindow(); 
// 2. Set a property 
win.title = "Hello World";
// 3. Call a method on the proxy.
win.open(); 

...

Although the win object appears like an ordinary JavaScript object to a Titanium application, it is important to remember that there are actually two objects – the JavaScript object and the native proxy object. Only properties and methods that are bound to the native proxy object actually invoke calls to the native proxy. Setting an arbitrary property on an object after creation time will add the property to the JavaScript object, but not the proxy object. Consider the following code:

Code Block
languagejs
var win = Ti.UI.createWindow();
win.myProp = "Some other string";
win.title = "Hello World";

In this example, setting the title property on win causes the title to be set on the native window proxy, but the myProp property is only set on the JavaScript object, and is not passed to the native layer.

 

Native

...

module objects

A module object is the native representation of a Titanium module. It extends a native module type (TiModule on iOS, KrollModule on Android). This native module type inherits from the native proxy type – like a proxy, a module exposes a set of properties and methods to JavaScript. In addition, the native module object can have an assigned identifier – used to import the module with `require` – and a set of lifecycle events that the module can respond to.

...

Every proxy object has a parent module. The parent module usually exposes methods for creating its child proxy objects, like the Ti.UI module provides a Ti.UI.createButton method to create a Ti.UI.Button object.

Views and

...

view proxies

For UI components, there are some additional classes you'll need to use. A view proxy is a special proxy type that extends TiViewProxy, which has additional properties and methods specific to the Titanium UI system. Each view proxy has a corresponding Titanium view type, which extends the TiUIView class. The view proxy provides a way for applications to interact with the view from JavaScript. The view object itself may be created and destroyed as needed – for example, the controls in a window don't need to be instantiated until the window is opened.  

...

  • When you set a property on the view proxy, the underlying native view may not exist. Therefore, the view proxy is responsible for maintaining the properties.
  • When a view is created, it is initialized with the current set of properties stored by the view proxy.
  • When a view proxy's properties are updated, the view is updated as well.

Converting

...

between JavaScript and

...

native objects

When you pass an object to a native method, or return an object from a native method or property to JavaScript, objects must be converted from JavaScript objects to native objects, and vice-versa.

...

  • Primitive values, such as numbers, strings and arrays can be converted to their equivalent values.
  • Plain JavaScript objects can be converted to native dictionary objects (Java HashMap or Objective-C NSDictionary, for example).
  • More complex types can be passed by creating a special proxy class to represent them.

Events and

...

callbacks

When performing an asynchronous operation, you can send data back to the JavaScript layer using events or callbacks.

...

Note

On the iOS platform, each JavaScript context operates in its own thread. If you create a Window using the url property, the window runs in a separate context and in a separate thread. For this reason, when communicating between JavaScript contexts on iOS, you should only pass serializable JavaScript objects, not functions or proxy objects.

When calling a callback from a module, the callback is invoked on the appropriate JavaScript runtime thread. When you fire an event from your module, the event listener function is called on the thread where the listener was added. (Potentially, this means that the same event could be delivered on multiple threads if your application has multiple contexts, each with a listener defined for that event.)

Packaged JavaScript and

...

hybrid modules

To package JavaScript as a native module, create a JavaScript module named <module-id>.js in the module's assets folder. The APIs exported by this module form the API of the packaged module.

...

If your module includes both JavaScript and native code, the native and JavaScript module contents are merged when the module is packaged. For example, if your native module exposes a createView method, and you have a JavaScript module that exposes a animateView method, both of these methods are available on your module:

Code Block
languagejs
var myModule = require("com.example.module");
var view = myModule.createView({ width: 200, height: 200 });
win.add(view);
myModule.animateView(view);