Gyroscope native extension sample
Requirements
Prerequisite knowledge
Familiarity with building mobile apps on Adobe AIR, including familiarity with Objective C and Xcode, or Android development.
Required third-party products
User level
Intermediate
Required products
Sample files
Note: By clicking the download link for any source examples on this page, you acknowledge that you have read and agree to the Adobe AIR SDK License Agreement. These files are considered Sample Code.
Note: Adobe recommends using the next version of Flash Builder for developing native extensions for Adobe AIR. Sign up now to get access to the prerelease of Flash Builder 4.6.
The Gyroscope class is a native extension for Adobe AIR. It allows AIR application developers, from ActionScript, to access the gyroscope data of an Android or iOS mobile device.
The attached ZIP file contains:
- The ActionScript library in the directory AS: This directory contains the Flash Builder project for creating the ActionScript side of the Gyroscope extension.
- The Android native library in the directory NativeAndroid: This directory contains an Eclipse project for creating the Android native side of the Gyroscope extension. To build the Eclipse project, first copy FlashRuntimeExtension.jar from <AIR_SDK>/lib/android/FlashRuntimeExtensions.jar to
the directory NativeAndroid\lib.
- The iOS native library in the directory NativeIOS: This directory contains an Xcode project for creating the iOS native side of the Gyroscope extension. To build the Xcode project, first copy FlashRuntimeExtension.h from <AIR_SDK>/include/FlashRuntimeExtensions.h to the directory NativeIOS\iosextension.
- A directory called Binaries: This directory contains everything the AIR application developer needs to use the native extension: the ANE file, the SWC file, and a text file that contains the extension ID.
- A directory called Eg: This directory contains a sample AIR application that uses the Gyroscope native extension.
The ActionScript library
The ActionScript library contains the Gyroscope class. The Gyroscope class provides the AIR application these public methods and properties:
public static function get isSupported(): Booleanpublic function setRequestUpdateInterval(newInterval:int): voidpublic function dispose(): void
The AIR application can create many instances of the Gyroscope class. However, the Gyroscope class creates only one ExtensionContext class instance that all the Gyroscope instances share.
Event handling
The native side of the extension dispatches a StatusEvent event that the ExtensionContext instance listens for:
extCtx.addEventListener(StatusEvent.STATUS, onStatus);
The event contains the the x, y, and z data of the device's gyroscope. The native side dispatches this event at the fastest rate possible for the native operating system.
Each Gyroscope instance dispatches an event of type class GyroscopeEvent at the interval set by setRequestUpdateInterval() for that instance:
private function onInterval(e:TimerEvent):void {
// For each Gyroscope instance, at the requested interval,
// dispatch the gyroscope data.
if (extCtx != null) {
dispatchEvent(new GyroscopeEvent(GyroscopeEvent.UPDATE, _x, _y, _z));
}
}
The dispose() method
The AIR application calls dispose() when it no longer needs gyroscope data. Each time the application creates an instance of the Gyroscope class, the constructor increments a reference count. The dispose() function decrements the reference count, and when the count is 0, dispose() calls a native function to stop providing gyroscope data to the ActionScript side.
Application usage
To use the Gyroscope extension, an AIR application does the following:
- Checks if the extension is supported by looking at the
isSupportedproperty. - Creates a Gyroscope object.
- Sets the Gyroscope object's update interval if the default value of 100 milliseconds is not the desired interval.
- Listens for the GyroscopeEvent event.
For example:
var gyro:Gyroscope;
if(Gyroscope.isSupported)
{
gyro = new Gyroscope();
gyro.setRequestedUpdateInterval(1000);
gyro.addEventListener(GyroscopeEvent.UPDATE,onChange);
}
The following code shows the event handler:
private function onChange(e:GyroscopeEvent):void
{
trace("From gyro: " + e.x + " " + e.y + " " + " " + e.z);
}
The Android native library
The Android native library is implemented in Java, using the native extension Java API. The native library includes the following classes:
- GyroscopeExtension implements FREExtension
- GyroscopeExtensionContext extends FREContext
- GyroscopeSupportedFunction, GyroscopeInitFunction, GyroscopeStartFunction, and GyroscopeStopFunction each implement FREFunction
The native library also contains the class GyroscopeListener. An object of this class receives the Android SensorEvent event, and in turn calls the GyroscopeExtensionContext object's dispatchStatusEventAsync().
The native library also contains examples of using these FREObject methods:
newObject()getAsInt()
In its initialization, the native library uses the getActivity() method of the FREContext class to get the application's Android Activity. Using the returned Activity, the initialization method (InitFunction.call()) gets the sensor service:
SensorManager sm = (SensorManager)extCtx.getActivity().getSystemService(Activity.SENSOR_SERVICE);
Note: The call from the ActionScript side to ExtensionContext.createExtensionContext() must return before the native library can call methods of the object derived from the FREContext class. Therefore, the call getActivity() occurs in the initialization function that the ActionScript side calls after the return from createExtensionContext(). The call to getActivity() cannot occur in the FREContext object constructor.
The iOS native library
The iOS native library is implemented in Objective C, using the native extension C API. The native library contains examples of these native extension C APIs:
- The extension initializer and finalizer, using the signatures of
FREInitializer()andFREFinalizer(). - The context initializer and finalizer, using the signatures of
FREContextInitializer()andFREContextFinalizer(). - Native functions, using the signature of
FREFunction(). The native functions includeADBE_GYRO_startGyro(),ADBE_GYRO_stopGyro(),ADBE_GYRO_supportGyro(), andADBE_GYRO_initStub(). FREDispatchStatusEventAsync()FRENewObjectFromBool()
The native functions use iOS classes such as CMMotionManager and CMGyroData to check if a gyroscope is available and to access the device's gyroscope data.
Note: In the iOS native implementation, no initialization is necessary, and so the initialization native function, ADBE_GYRO_initStub() , does nothing. However, the function is necessary because the Android native implementation requires an initialization function. Therefore, to make the extension's ActionScript interface the same for all native implementations, the iOS native implementation provides the stub.
Where to go from here
For more information about developing native extensions for Adobe AIR, see:
For more information about using a native extension in an AIR application, see:
