Hey everybody and welcome to another episode of Forging Titanium. This week's episode is part 1 of a 3 part series where we will create a fun experiment called "Twisti" that'll make use of a native Android module, 3D graphics and rendering, and realtime communication via sockets. Today we'll be exploring how we can use a native Android module to extend the functionality present in the Titanium.Accelerometer module.
The first thing you should do before embarking on native module development is check out the comprehensive guides in the wiki. Here you can find everything you need to get started creating your own native modules. The guides also serve as a great reference for even veteran module developers. If anything in this screencast is confusing and you need further clarification, those guides would be your best bet.
Before you can create an Android module, you need to make sure you have all prerequisites accounted for, as listed here. If you are missing any of these, be sure to follow the links in the wiki to get the necessary packages. One additional note is that we'll be developing this module using Eclipse, as it is Google's preferred IDE for Android development so you'll likely want to install that as well.
One final step is to make sure your command line environment is prepared for module development. Follow the Titanium Command Line Interface guide that details for each supported OS how you can run the module build scripts. It should take you less than a minute to get that ready for your OS.
OK, everything should now be in place, let's create the Android module. Open up our command line interface and type in the following command...
The titanium script, which you should now have in your PATH as per the Titanium Command Line Interface guide, will be given an action of create. When create is designated, we give it the following series of arguments to indicate that we'll be creating a native module. type and platform indicate that we are building a native module for android, respectively. Next we give the module a name and id, very much like normal project creation in Titanium Studio. Finally, we give the build script the path to our Android SDK. You will obviously need to change this to the path appropriate to your system.
When we run this command we'll then receive the anticlimactic message "created android module project". Let's take a quick peek inside of our newly created project directory. We can see that the Titanium build script did a lot of the grunt work for us in terms of creating a project that we can almost immediately use as a Titanium module. To get an even better look, let's load this project into Eclipse...
With Eclipse open we'll go to file -> import -> existing projects into workspace. Click "browse" and go to the root of the newly created module directory. Click finish and the module is then loaded into Eclipse. There's lots of files and directories here, all of which are discussed in detail in the module development wiki guides. Today we're only going to discuss the necessary changes for creating a module that returns additional sensor data from Android.
Let's open up the source directory in our project and find the TwistiModule.java file. In here we see the basic layout for module level code. Notice the @Kroll annotations throughout the class definition. These annotations are how modules, properties, and methods are exposed to Titanium's Javascript API via your native module.
So we have this default module... what do we do with it? Where can we get examples of how to add functionality to it? Fortunately for us, the open source Titanium mobile SDK has loads of them. For those unaware, the core Javascript API for Titanium is effectively just a series of native modules, built in this same fashion, that have been integrated into the SDK.
Let's go out to github and check out the existing accelerometer module in the SDK. In the titanium_mobile project, in the android modules section, we see a listing of all the modules exposed by the core Titanium Javascript API. If we click through to the source code for the module... we find a relatively small, concise blueprint for registering sensor events and then sending them back through the Javascript API. Don't worry if you don't understand all, or any, of this code right now. The important lesson here is that when you do decide to dive into native module development, the titanium_mobile SDK itself is a treasure trove of examples written by Appcelerator's platform engineers.
Let's go back to Eclipse and take a look at the module I have already created for this experiment, basing it largely on the existing Accelerometer module for Android. At the very beginning of the class definition you'll notice that this module, like the SDK's Accelerometer, implements SensorEventListener. Implementing this class is what allows us to receive native sensor events from android devices. The majority of the variables created here are for 3 dimensional calculations based on the accelerometer and magnetic field values we receive and are used a little later in the code.
We are still using the default module constructor. Below it we see methods for both adding and removing event listeners. We override these functions so that we can have more control over how and when they are registered. The onAccuracyChanged function is not used by our module and is given a default, empty implementation.
Finally we arrive at the onSensorChanged function. This is the function that will be called whenever Android receives a sensor event for which we've registered. The first thing we do is identify which sensor sent the event, then store it's values for later use. We do this because we need both the current accelerometer and magnetic field values to perform the upcoming 3D transformations.
When we do have both of these values, we perform a series of 3D operations provided by Android that I'm not even going to pretend to fully understand. What is effectively happening is that the gravity vector provided by the accelerometer is used in conjunction with the direction of the magnetic field to deliver a set of values that give the physical orientation of the device relative to magnetic north. You got all that?
In the end, we'll send back to our Titanium app, via an event, the latest x, y, and z values from the accelerometer, as well as the azimuth, pitch, and roll representing the orientation of the device.
Building this module so that we can use it in our Titanium apps is simple. We just go back out the command line interface, make sure we are at the top level of the module's project directory, then type ant. ant will launch our build scripts and if you have everything configured correctly, you will see a BUILD SUCCESSFUL message after a few seconds. If we then go into the dist, or distribution, directory, we'll find our module ready for use. The naming convention seen here for the zipped module is the module id followed by the platform followed by the version.
With our native Android module created, let's open up Titanium Studio to the sample app I've prepared to test it. The app will simply include the new module via the require() function, listen for sensor events on it, and then report the sensor data with a few Titanium labels. As you can see, there's not much Javascript code necessary to do so. Once we get past the simple UI creation, we find the interesting part down here at the bottom. This is where we include the twisti module, attach the event listener, and then update the UI labels based on those events.
Before we can launch this code, though, we need to make sure our Titanium app can access our new module. To prepare our app, we first need copy the module's zip file into the root of our project directory. When you run your app, the build scripts will identify the module zip file and unarchive it to the modules directory.
On additional step is to modify your tiapp.xml file to indicate you will be using the module. All you need to do is add a module element to the existing modules section in tiapp.xml. If we look here... we see the module has a single attribute that specifies the version, and the value of the element is the module's id. If you forgot these values, remember they are actually included in the module's zip file name. They can also be found in the manifest file at the root of your module's project directory.
With the module included in our project and specified in the tiapp.xml, we are ready to test. Because we are planning to use sensor data unavailable in the android emulator, we are going to push this app out to an android device. So let's switch gears here and see how our native Android module behaves on device...
LIVE VIDEO
Today in the first part of the this 3 part series, we saw how we can create a native Android module to expose sensor data not available in the core Titanium Javascript API. Using Android's sensors and coordinate processing we are able to deliver the physical orientation values back to our app. In addition, we took a sneak peek at what's in store for part 2 of this series, where we'll use those values to create a 3 dimensional, canvas-based scene in our Titanium app. It's a great demonstration of how Titanium allows you to leverage native, platform specific features, abstracted native UI, and web-based mobile development in a way that is pretty unique.
Thanks for watching this episode of Forging Titanium. Hope to see you back here next week for part 2. See ya then.