Skip to end of metadata
Go to start of metadata

Introduction

The Titanium SDK is based on a modular architecture, which can be utilized to extend the SDK by building modules.  The module architecture contains the following key interface components:

  • Module : A base class that represents the native binding between your JavaScript code and native code
  • View : The visual representation of a UI component which Titanium can render

To return visual data between JavaScript and native code, create a View. The View represents is responsible for exposing the APIs and events that the View supports.

To return non-visual data between JavaScript and native code, create a Module. The Module knows how to handle any method and property, and dispatching and firing events.

These components require special class names and method signatures.  Each components is described in further detail below.

Module

A Module is a class that provides an API point with a particular ID. That ID can then be used to require the module from JavaScript.

All modules must extend the Titanium::Module and JSExport class .

ComExampleTest.hpp

Module constructor should call Titanium::Module constructor with module id that specifies the identifier used with require to import the module.

ComExampleTest.cpp

In this case, the JavaScript to require the module would look like this:

A module can also have a parent module: for instance Titanium.UI and Titanium.App are children of the Titanium module.

Module Lifecycle Events

The module provides several places for you to hook into the application's lifecycle.

Use postInitialize method to declare a method to be called when the module object is created. This is optional and is only required if you have any module specific initialization, such as initializing variables that is required by the module. This method is called after module object initialization. This method could be called multiple times, after your module object is actually created, and before module is called as a constructor.

Declare postInitialize with override specifier in the header:

ComExampleTest.hpp

Override postInitialize in the implementation:

ComExampleTest.cpp

If you only need to hook JavaScript constructor, use postCallAsConstructor method to declare a method to be called when the module constructor is called. This is optional and is only required if you have any module instance specific initialization, such as initializing variables that is required by the instance. This method is called during module constructor. This method is called only once after module is called as a constructor.

Declare postCallAsConstructor with override specifier in the header:

ComExampleTest.hpp

Override postCallAsConstructor in the implementation. Note that the arguments that is given to the constructor are passed as arguments parameter.

ComExampleTest.cpp

Methods

Methods are exposed via TITANIUM_ADD_FUNCTION and TITANIUM_FUNCTION_DEF C++ macro.

First, declare method using TITANIUM_FUNCTION_DEF in header:

ComExampleTest.hpp

Second, implement example method with TITANIUM_FUNCTION and then register in JSExportInitialize with TITANIUM_ADD_FUNCTION:

ComExampleTest.cpp

There are variables expanded from TITANIUM_FUNCTION macro here: arguments as std::vector<JSValue>, and this_object as JSObject.

Titanium provides several ways for typecasting incoming values to a specific type and extracting them from the array that can be used with TITANIUM_FUNCTION. For instance you can find ENSURE_XXX_AT_INDEX for typecasting, that is defined in Titanium/detail/TiImpl.hpp.
  • ENSURE_INT_AT_INDEX(OUT, INDEX)
  • ENSURE_UINT_AT_INDEX(OUT, INDEX)
  • ENSURE_DOUBLE_AT_INDEX(OUT, INDEX)
  • ENSURE_BOOL_AT_INDEX(OUT, INDEX)
  • ENSURE_STRING_AT_INDEX(OUT, INDEX)

Note that in this macro example OUT is a variable name, and INDEX is a index in the arguments. For example:

 

ComExampleTest.cpp

Properties

Properties are exposed via TITANIUM_ADD_PROPERTY and TITANIUM_PROPERTY_DEF C++ macro.

First, declare method using TITANIUM_FUNCTION_DEF in header:

ComExampleTest.hpp

Second, implement exampleProp property getter/setter with TITANIUM_PROPERTY_GETTER/ TITANIUM_PROPERTY_SETTER and then register in JSExportInitialize with TITANIUM_ADD_PROPERTY:

ComExampleTest.cpp

Inside setter, there's a variable that you can use: argument as JSValue. For typicasting property values, you can just use C++11 static_cast<TYPE>.

ComExampleTest.cpp

Handling Events

Modules automatically handle firing events and managing event listeners. Internally, when you call addEventListener() or removeEventListener() from JavaScript against a module instance, the module will automatically handle the code for managing the event listeners. If you want to be notified upon an add or remove, you should override the methods:

ComExampleTest.hpp

The enableEvent method will be invoked when event is enabled with given name. This is convenient, for example, when you would like to enable some action only once at least one listener is listening for the event. This can be useful for conserving system resources.

The disableEvent method will be invoked when event is enabled with given name. This is useful when you want to cleanup system resources once no listeners are actively listening for events.

To send an event to any event listener, you use the convenience method:

Titanium/Module.hpp

The first one is the default and most common way to fire an event. The first argument (name) is the event name. The second argument (event) is an JSObject of event properties. The second argument can also be omitted if no additional event properties are needed. The event properties will be part of the event argument which is the first argument in all event functions.

For example:

In this example, we'd adding one additional event property named 'name' with the value of 'my name'. In JavaScript, this would be retrieved like:

In addition to any additional event arguments passed, Titanium automatically provides the following built-in properties on all events fired:

  • source — The source object (proxy) that fired the event
  • type — The type of event

More Examples

  • No labels