BETA ActionScript® 3.0 Reference for the Adobe® Flash® Platform
Home  |  Hide Packages and Classes List |  Packages  |  Classes  |  What's New  |  Index  |  Appendixes

Language Reference only
Filters: AIR 32.0 and earlier, Flash Player 32.0 and earlier, Flash Lite 4
None
Hide Filters
flash.sensors 

DeviceRotation  - AS3

(Beta)
Packageflash.sensors
Classpublic class DeviceRotation
InheritanceDeviceRotation Inheritance EventDispatcher Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 26.0

The DeviceRotation class dispatches events based on activity detected by the device's acceletometer, gyroscope sensors. This data represents the device's roll, pitch, yaw and quaternions. When the device rotates, the sensors detect this rotation and return this data. The DeviceRotation class provides methods to query whether or not Device rotation event handling is supported, and also to set the rate at which device rotation events are dispatched.

Note: Use the DeviceRotation.isSupported property to test the runtime environment for the ability to use this feature. While the Device rotation class and its members are accessible for multiple runtime platforms and devices, this does not imply that the handler is always supported at the runtime. There are a few cases such as Android version etc where this handler is not supported, so you must check the support of this handler by using DeviceRotation.isSupported property. If DeviceRotation.isSupported is true at runtime, then DeviceRotation support currently exists.

AIR profile support: This feature is supported only on mobile devices. It is not supported on desktop or AIR for TV devices. See AIR Profile Support for more information regarding API support across multiple profiles.

Related API Elements



Public Properties
 PropertyDefined By
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
      isSupported : Boolean
[static] [read-only] The isSupported property is set to true if the accelerometer and gyroscope sensors are available on the device, otherwise it is set to false.
DeviceRotation
      muted : Boolean
[read-only] Specifies whether the user has denied access to the Device Rotation data (true) or allowed access (false).
DeviceRotation
Public Methods
 MethodDefined By
  
    DeviceRotation()
Creates a new DeviceRotation instance.
DeviceRotation
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
The setRequestedUpdateInterval method is used to set the desired time interval for updates.
DeviceRotation
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  
    status
Dispatched when device rotation changes its status.DeviceRotation
  
    update
The update event is dispatched when the device is rotated in response to updates from the combined readings from accelerometer and gyroscope sensors.DeviceRotation
Property Detail
    

isSupported

property
isSupported:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 26.0

The isSupported property is set to true if the accelerometer and gyroscope sensors are available on the device, otherwise it is set to false.



Implementation
    public static function get isSupported():Boolean

Example  ( How to use this example )
In the following example, the DeviceRotation.isSupported property is used to test for DeviceRotation support at runtime. If the current environment supports the DeviceRotation feature, then an event listener is added to the DeviceRotation object, and the associated handler populates the text field with the timestamp and roll,yaw and pitch values. Otherwise, the text field indicates that the feature is not supported in the current environment.
var myTextField:TextField = new TextField();
myTextField.width = 200;
addChild(myTextField);
var deviceRotation = new DeviceRotation();
var isSupported:Boolean = DeviceRotation.isSupported;
checksupport();

function checksupport():void {
    if (isSupported) {
        myTextField.text = "DeviceRotation feature supported";
        deviceRotation.addEventListener(DeviceRotationEvent.UPDATE,deviceRotUpdateHandler);
    } else {
        myTextField.text = "DeviceRotation feature not supported";
    }
}

function deviceRotUpdateHandler(evt:DeviceRotationEvent):void {
    myTextField.text = String("at: " + evt.timestamp + "\n" + "Roll: " + evt.roll + "\n" + "Yaw: " + evt.yaw + "\n" + "Pitch: " + evt.pitch);

}
    

muted

property 
muted:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 26.0

Specifies whether the user has denied access to the Device Rotation data (true) or allowed access (false). When this value changes, a status event is dispatched.



Implementation
    public function get muted():Boolean

Related API Elements

Constructor Detail
    

DeviceRotation

()Constructor
public function DeviceRotation()

Language Version: ActionScript 3.0
Runtime Versions: AIR 26.0

Creates a new DeviceRotation instance.

Method Detail

    setRequestedUpdateInterval

()method
public function setRequestedUpdateInterval(interval:Number):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 26.0

The setRequestedUpdateInterval method is used to set the desired time interval for updates. The time interval is measured in milliseconds. The update interval is only used as a hint to conserve the battery power. The actual time between device rotation vector updates may be greater or lesser than this value. Any change in the update interval affects all registered listeners. You can use the DeviceRotation class without calling the setRequestedUpdateInterval() method. In this case, the application receives updates based on the device's default interval.

Parameters

interval:Number — The requested update interval. If interval is set to 0, then the minimum supported update interval is used.


Throws
ArgumentError — The specified interval is less than zero.
Event Detail
    

status

Event
Event Object Type: flash.events.StatusEvent
property StatusEvent.type = flash.events.StatusEvent.STATUS

Language Version: ActionScript 3.0
Runtime Versions: AIR 26.0

Dispatched when device rotation changes its status.

Defines the value of the type property of a status event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
codeA description of the object's status.
currentTargetThe object that is actively processing the Event object with an event listener.
levelThe category of the message, such as "status", "warning" or "error".
targetThe object reporting its status.
    

update

Event  
Event Object Type: flash.events.DeviceRotationEvent
property DeviceRotationEvent.type = flash.events.DeviceRotationEvent.UPDATE

Language Version: ActionScript 3.0
Runtime Versions: AIR 26.0

The update event is dispatched when the device is rotated in response to updates from the combined readings from accelerometer and gyroscope sensors. The event is dispatched in the following circumstances:

  • When a new listener function is attached through addEventListener(), this event is delivered once to all the registered listeners for providing the current value of the device rotation vector in terms of roll pitch and quaternions.
  • Whenever device rotation updates are obtained from the platform at device determined intervals.
  • Whenever the application misses a change in the device rotation (for example, the runtime is resuming after being idle).

Defines the value of the type property of a DeviceRotationEvent event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
timestampThe timestamp of the DeviceRotation update.
rollThe roll value in degrees.
pitchThe pitch value in degrees.
yawThe yaw value in degrees.
quaternion The quaternion data in [w, x, y, z] format