Android module development guide in Titanium

 
 

  
  
@Kroll.proxy   
  
  
public class MyProxy extends KrollProxy {   
  
  
  @Kroll.method(runOnUiThread=true)   
  
  
  public int doSomething() {   
  
  
    return 100;   
  
  
  }   
  
  
}   
 
 

Official Address: Android Module Development Guide

Summary

This guide teaches you how to develop the Android module in Titanium to expand Titanium functions. In this guide, you will learn the following:

• Set your environment to build the Android Module
• Build an Android Module
• Package an Android Module
• Understand the Android module API

Titanium Android Module Development Guide

To use the Android SDK, you must have knowledge about the Android SDK. This Guide assumes that you know how to use the native Android SDK for development.

Prerequisites

• Titanium Mobile SDK 1.5 and later
• The latest version of Python (> = 2.5) must be in the PATH or define the PYTHONHOME constant. In Windows, Titanium Developer/Desktop is bound to Python2.5, so no additional configuration is required.
• Oracle JDK
• Android SDK
• Ant 1.7.1 or later versions must be included in the PATH. If you do not want to install Ant separately, you can use Eclipse

Environment Settings

Complete environment settings by referring to the Titanium command line tool.

Create a module

To create a module, we need to pass some parameters to the titanium command line tool.

• Module name ($ MODULE_NAME) and ID ($ MODULE_ID)
• Target running platform of the module (android)
• Android SDK installation directory ($ ANDROID_SDK) such as/opt/android-sdk

For an Android system, we create a module with the following parameters:

Reference

Titanium create -- platform = android -- type = module -- name = $ MODULE_NAME -- id = $ MODULE_ID -- android = $ ANDROID_SDK

As an example, we created a module that runs simple addition and subtraction operations, named "calc", and assigned its ID as "org. appcelerator. and direct the Android SDK path to/path/to/android-sdk

Reference

Titanium create -- platform = android -- type = module -- name = calc -- id = org. appcelerator. calc -- android =/path/to/android-sdk

If it runs successfully, you can see the newly created calc subdirectory in the current directory.

Module project directory Layout

In the Module Directory, you can see the newly produced file and directory tree:

• LICENSE-module copyright description
• The properties file of build. properties-Ant, including the paths of Titanium SDK and Android SDK
• Build. xml-Ant build script-used to build, distribute, and Test Modules
• Manifest-list file containing the module version, author, license, copyright, name, ID, GUID, and platform information
• Timodule. xml-place custom activities and configure to insert them to the AndroidManifest. xml file
• Hooks-script directory, called when the module is added, installed, deleted, or uninstalled
• Documentation-the generated Markdown file contains the example document of your module
• Assets-other resources required by the module (For details, refer to README)
• Lib-place the required third-party JAR files, they will be automatically appended to your project and module zip [*] src-Module source code directory
• Example-module example project

Eclipse Integration

TItanium will create the files required for importing the Eclipse project. In Eclipse, execute the following operations to import the calc project:

• Click "File> Import…" in the top menu ..."
• Open the General folder and double-click "Existing Project into Workspace"
• Click "Browse…" after "Select root directory ..."
• Select the module project directory
• You can see your module in the Projects List:
  
• After you press "Finish", you should be able to see your module project under "Package Explorer" of Eclipse.

Build module zip

The zip package under the dist directory is a module's allocable form. Normally, the model is $le_id-android-$module_version.zip.

Including:

• Compiled inclusion classes, generated bindings, and JAR packages of resource files
• Third-party JAR packages in the lib directory
• Module list, including author, version, license, copyright, and other metadata required for deployment
• Module timodule. xml file

Build from command line with Ant

If ant is already in PATH, you can simply execute it in the module's top-level directory, and you will see the following output:

Reference

$ Ant Buildfile:/Users/marshall/Code/test/test_modules/calc/build. xml Init: [Mkdir] Created dir:/Users/marshall/Code/test/test_modules/calc/build/classes [Mkdir] Created dir:/Users/marshall/Code/test/test_modules/calc/dist Process. annotations: [Javac] Compiling 2 source files to/Users/marshall/Code/test/test_modules/calc/build/classes [Javac] Note: [KrollBindingGen] Running Kroll binding generator. [Javac] Note: [KrollBindingGen] No binding data found, creating new data file. [Javac] Note: [KrollBindingGen] Found binding for module Calc [Javac] Note: [KrollBindingGen] Found binding for proxy Example Compile: [Javac] Compiling 2 source files to/Users/marshall/Code/test/test_modules/calc/build/classes [Copy] Copying 1 file to/Users/marshall/Code/test/test_modules/calc/build/classes Dist: [Jar] Building jar:/Users/marshall/Code/test/test_modules/calc/dist/calc. jar [Zip] Building zip:/Users/marshall/Code/test/test_modules/calc/dist/org.appcelerator.calc-android-0.1.zip BUILD SUCCESSFUL Total time: 1 second

Build from Eclipse

If you have installed Ant or want to use Eclipse, follow these steps:

• Right-click the build. xml file in the Module Directory.
• Click RunAs> AntBuild
• You will see similar output

Module Distribution

To use modules in the TitaniumMobile application, follow these steps:

[List]

• Copy the zip file of the module to the root directory of the Titanium application or the root directory of the TitaniumSDK.
• Add the following xml to the tag of the tiapp. XML file of the application:

Xml Code

 
 

  
  
<!-- $MODULE_VERSION should be the same as "version" in the module manifest -->    
  
  
[*]<modules>    
  
  
[*]    <module version="$MODULE_VERSION">$MODULE_ID</module>    
  
  
[*]    <!-- For example, if we were adding the calc module: -->    
  
  
[*]    <module version="0.1">org.appcelerator.calc</module>    
  
  
[*]</modules>    
 
 

• Use the require function in the application code to include the module code to the application. For example:

  
  

   
   
var Module = require('$MODULE_ID');   
   
   
[*]// For example, to load the calc module:   
   
   
[*]var Calc = require('org.appcelerator.calc');   
  
  

• When the next application starts or component, the module should be included in the application. [/list]
  

  Test with embedded Example project

  The simplest way to make your module work is in example/app. write code in the js file and use ant to run and test the module code. the example directory is equivalent to the Resources directory of the application.

  The process of running the sample project is very simple:

• Run the android Simulator
• After the simulator starts, you can run your module code.

Run the Android Simulator

Run the following command in the module project:

Reference

Ant run. emulator

You should see the simulator output in the console!

Configure the call information in Eclipse:

• Right-click build. xml and choose Run As> Ant Build... (Option 2)
• For a new startup configuration, a configuration setting window is opened.
• Select the execute object, remove the ** dist object, and select the run. emulator object.
• Rename the startup configuration, but it clearly shows the meaning, such as "run emulator"
• An example of Window Length: calc module:
• Click Apply and then run
• In this way, you can run the startup configuration through the run of the external tool menu or toolbar.
• You should be able to see that emulator has output information in the Eclipse Console window.

Run the Example project

Once the emulator is up and running, you just need to wait for the unlock screen to appear, and you can start running your project. make sure to unlock the screen so you'll see the example project when it launches.

From command line, run this inside your module project:

Reference

Ant run

Set the startup configuration in Eclipse:

Follow the same steps from the Launch configuration setup above, but use the run target instead of the run. emulator target. You shoshould also name the configuration something different, for example run calc project

Troubleshooting tips:

If the running object times out, find the emulator and run the following command to restart the ADB service:

$ ANDROID_SDK/tools/adb kill-server $ ANDROID_SDK/tools/adb start-server

Here, if you successfully run the module example project, you will see the default "hello world" application in the simulator:

Generation module and Example proxy

As part of the initial project creation, Titanium generates the classes used in two sample projects:

• Module class, such as src/org/appcelerator/calc/CalcModule. java
• Proxy class, such as src/org/appcelerator/calc/ExampleProxy. java

Let's take a look at the code to see how Modules and Proxies communicate with Javascript. In the next section, we will briefly introduce Titanium and Kroll APIs.

Android Titanium API

Module and proxy (Kroll part 1)

• A module is a static and optional top-level interface point that can always be accessed by the same name. titanium. UI and Titanium. app is an example of two modules under the TItanium object of the top-level API.
• A proxy is a dynamic object that can be created and queried through one module or another agent. when you use "Titanium. UI. createView: When the http://developer.appcelerator.com/apidoc/mobile/latest/Titanium.UI.createView-method.html creates a native view, the view object itself is a proxy
• Both the module and proxy can export methods, attributes, constants, and getters/setters methods to Javascript APIs.

Module

• You must use the @ Kroll. module symbol to mark and inherit the KrollModule class.
• The module can have a parent module, for example, the "Titanium. App. Properties" http://developer.appcelerator.com/apidoc/mobile/latest/Titanium.App.Properties-module module exists under Titanium. App
• You can specify a unique ID for require ()
• Can be exported as a top-level object (same as Titanium)

Proxy

• The @ Kroll. proxy symbol must be used for annotation and inherit the KrollProxy class.
• When @ Kroll. proxy # creatableInModule () is used, there is a generated "create" method.
• Built-in Event Management

Export method and attributes (Kroll part 2)

Method

The proxy and module methods are exported using the @ Kroll. method symbol. The following is a simple example:

Java code

 
 

  
  
@Kroll.method    
  
  
public String getMessage() {    
  
  
    return "Hello World";    
  
  
}    
 
 

If the method you export requires the current Activity, you can add KrollInvocation as the first parameter:

Java code

 
 

  
  
@Kroll.method   
  
  
public String getMessage(KrollInvocation invocation) {   
  
  
    Activity activity = invocation.getTiContext().getActivity();   
  
  
}   
 
 

There are many other options in the method. For more information, see @ Kroll. methodJavadoc.

Attribute

Attributes can be exported in two different forms:

1. The getter/setter method is exported using the @ Kroll. getProperty and @ Kroll. setProperty symbols. The Getter/setter method can also be exported as the Kroll method (this is a common mode in Titanium)

2. Use the Kroll. property symbol to export an object field (using reflection, the speed is a little slow)

In this example, a getter and setter are exported for the message property, and the method with the same name is as follows:

Java code

 
 

  
  
@Kroll.getProperty @Kroll.method   
  
  
public String getMessage() {   
  
  
        return "Hello World";   
  
  
}   
  
  
@Kroll.setProperty @Kroll.method   
  
  
public void setMessage(String message) {   
  
  
    Log.d(TAG, "Tried setting message to: " + message);   
  
  
}   
 
 

In Javascript, you can use the following code:

Js Code

 
 

  
  
var object = //..   
  
  
object.message = "hi"; // or   
  
  
object.setMessage("hi");   
 
 

Constant

Constants are static attributes in @ Kroll. module. This field is marked with the "@ Kroll. constant" symbol, which must be static and final. Here is an example:

Java code

 
 

  
  
@Kroll.module   
  
  
public class MyModule extends KrollModule {   
  
  
    @Kroll.constant   
  
  
    public static final int CONSTANT = 100;   
  
  
}  
 
 

Constants can be directly used: Ti. My. CONSTANT = 100

View

In Titanium, the view must have two classes ::

View Proxy: subclass of TiViewProxy

• Exposes view attributes and methods to JavaScript (same as the general proxy ).
• Implement the createView (Activity activity) method of TiUIView to return an instance of TiUIView.
• Most of the time, you want to call your UIView In the UI thread, refer to @ Kroll. method # runOnUiThread

View implementation: subclass of TiUIView

• You must use an instance of the view to call setNativeView, whether in the constructor or in processProperties.
• View implementation obtains data from the View proxy and applies the data directly to the local View.
• This class can selectively implement propertyChanged and processProperties. If you set properties in proxy, you will be notified.

As a simple example, refer to the Button implementation methods ButtonProxy and TiUIButton

Heavyweight and lightweight window

When you use the Titanium. UI. createWindow API to create a window, run some checks to check whether heavy weight is created:

• If a window is set with any of the following attributes, it is "heavyweight": fullscreen, navBarHidden, modal, windowSoftInputMode, or tabOpen: true
• Instead, it is "lightweight".
• The Heavyweight window generates a new Activity in the stack and creates a new Javascript Context for the window.
• When the Lightweight window is created, a full-screen View call code is the same Activity). If the url attribute is set, a new Javascript Context is created for each window.

Thread Security

When calling a method or attribute from any Activity or Thread in the Context of Javascript, it is important to ensure Thread security when designing your API.

To ensure that a method is executed on the UI thread, refer to @ Kroll. method # runOnUiThread (). The following is an example:

Java code