GameInputDevice - Adobe ActionScript® 3 (AS3 ) API Reference

Package	flash.ui
Class	public final class GameInputDevice
Inheritance	GameInputDevice Object

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

The GameInputDevice class represents a single input device commonly used for gaming.

This class includes methods and properties that you can use to:

Enable or disable an input device. Devices are initially disabled by default (enabled set to false). You must explicitly enable a device, by setting enabled to true, before you can get control values from the device.
Get the name and ID of an input device. The name and id properties together uniquely identify a device. For Android devices, the device manufacturer supplies these values. For iOS devices, the id may change each time you connect the device.
Enumerate the controls on an input device. Physical controls on a device are mapped to logical GameInputControl objects and stored in a list. You access a control in the list with the getControlAt() method.
Manage caching of sampled control values. Sampling a set of control values directly from a device object is one of three ways to get control values. (The other two ways use the value method on the GameInputControl class, and are described there.) Sample caching is useful when you need to access control values at a faster rate than the frame rate of an application.

Always set up a listener on this class for the GameInputEvent.DEVICE_REMOVED event. This listener lets you handle the case of a device being unexpectedly disconnected or powered off. When a device is disconnected, free its GameInputDevice object, as the object is no longer valid after its associated device is disconnected.

An Android device that is removed and then reconnected retains the ID it had when it was first connected. You can logically reconnect to a device by matching its ID. For iOS devices, the ID may change when you reconnect the device.

Note: You cannot rely on the order of devices in the list. (The order can change when devices are added and removed.)

For more information, see the Adobe Air Developer Center article: Game controllers on Adobe AIR.

For Android, this feature supports a minimum Android OS version of 4.1 and requires the minimum SWF version 20 and namespace 3.7. For iOS, this feature supports a minimum iOS version of 9.0 and requires the minimum SWF version 34 and namespace 23.0.

Related API Elements

flash.ui.GameInput
flash.ui.GameInputControl
flash.events.GameInputEvent

Public Properties

Hide Inherited Public Properties

Show Inherited Public Properties

	Property		Defined By
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		enabled : Boolean Enables or disables this device.	GameInputDevice
		id : String [read-only] Returns the ID of this device.	GameInputDevice
		name : String [read-only] Returns the name of this device.	GameInputDevice
		numControls : int [read-only] Returns the number of controls on this device.	GameInputDevice
		sampleInterval : int Specifies the rate (in milliseconds) at which to retrieve control values.	GameInputDevice

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		getCachedSamples(data:ByteArray, append:Boolean = false):int Writes cached sample values to the ByteArray.	GameInputDevice
		getControlAt(i:int):GameInputControl Retrieves a specific control from a device.	GameInputDevice
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		startCachingSamples(numSamples:int, controls:Vector.<String>):void Requests this device to start keeping a cache of sampled values.	GameInputDevice
		stopCachingSamples():void Stops sample caching.	GameInputDevice
		toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions.	Object
		toString():String Returns the string representation of the specified object.	Object
		valueOf():Object Returns the primitive value of the specified object.	Object

Public Constants

	Constant		Defined By
		MAX_BUFFER_SIZE : int = 32000 [static] Specifies the maximum size for the buffer used to cache sampled control values.	GameInputDevice

Property Detail

enabled

property

enabled:Boolean

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Enables or disables this device. Devices are disabled by default. Enable a device to access or sample its control values. Also, a device and its individual controls dispatch events only when the device is enabled.

When a device is removed, it becomes disabled. You can still get information about a disabled device, but you cannot access control values or start caching. Also, you cannot enable the device if it has been removed. If a device is removed, enabled always returns false.

Implementation
public function get enabled():Boolean
public function set enabled(value:Boolean):void

id

property

id:String [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Returns the ID of this device. You can differentiate devices by their IDs.

Note: For Android devices, the device manufacturer provides device IDs. For iOS devices, the ID may change when you reconnect the device.

Implementation
public function get id():String

name

property

name:String [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Returns the name of this device. The name can help to identify the type of device.

Note: The device manufacturer provides the names of its devices.

Implementation
public function get name():String

numControls

property

numControls:int [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Returns the number of controls on this device.

Implementation
public function get numControls():int

sampleInterval

property

sampleInterval:int

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Specifies the rate (in milliseconds) at which to retrieve control values. The default is 0, which means that values are updated once per frame. Setting a higher sampleValue directs GameInput to sample control values at a rate faster than the application's frame rate.

Although values can be updated more frequently than once per frame, only one event per control is dispatched. Therefore, if two updates to a value occur in one frame, only one change event is dispatched, and only the newest value can be retrieved.

To retrieve more than just the newest value, you can cache sample values by using the cache methods in this class. When you cache sampled values, this property determines how frequently values are written to the cache.

The default value is 0.

Implementation
public function get sampleInterval():int
public function set sampleInterval(value:int):void

Throws

	`IOError` — When the device is disabled while setting this property.

	`RangeError` — When the `sampleInterval` is less than 0.

Method Detail

getCachedSamples

()

method

public function getCachedSamples(data:ByteArray, append:Boolean = false):int

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Writes cached sample values to the ByteArray. The cached sample values are written to the ByteArray in the order they were retrieved (oldest values first, newest values last).

This method returns the number of cached sample values written to the ByteArray (not the values themselves). If the append parameter is false (the default), then the ByteArray is cleared before the sample values are written from the cache. If append is true, then the sample values are appended to the ByteArray, preserving the older values. Append sample values if:

You must keep a specific number of values available.
You must keep a history larger than the cache.

Important: If append is true, it is the responsibility of the application to clear the ByteArray. If the ByteArray is not cleared, it continues to grow, potentially crashing the application.

The cache is cleared after the sample values are written to the ByteArray.

An IOError is thrown if the device is disabled when this method is called.

Parameters

	`data:ByteArray` — The ByteArray that holds the retrieved data. It is filled with sample values written as doubles. The ByteArray holds NaN as the value of an control in case no change is detected in the control's position.

	`append:Boolean` (default = `false`) — A flag that determines how the data is written to the `ByteArray`. If `true`, the sampled values are written to the end of the array. If `false`, the contents of the `ByteArray` are removed and then the data is written to the array. The default is `false`.

Returns

int — The number of samples (not values) written to the ByteArray.

Throws

	`ArgumentError` — When `data` is null.

	`IOError` — When this method is called and the device is disabled.

getControlAt

()

method

public function getControlAt(i:int):GameInputControl

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Retrieves a specific control from a device.

GameInputDevice stores the controls on a device in a list. You can access individual controls on a device using the getControlAt() method.

The order of control in the index may change whenever a device is added or removed. You can check the id property on a GameInputControl object to match a specific control.

You can get controls even if a device is not enabled. However you cannot read control values from a disabled device. This feature lets you read a control's properties before you enable the device it belongs to. You can use this capability to determine whether a device is appropriate for your application before you enable the device.

Parameters

i:int — The index position of the GameInputControl in the list of GameInputControls.

Returns

GameInputControl — The GameInputControl object in the specified index position.

Throws

RangeError — When the index is less than zero or greater than (numControls - 1).

startCachingSamples

()

method

public function startCachingSamples(numSamples:int, controls:Vector.<String>):void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Requests this device to start keeping a cache of sampled values. The sampleInterval property determines the frequency of sampling. The numSamples parameter specifies the number of samples to cache. The controls parameter specifies the ID values of the controls to sample.

Control values are cached in the order specified. You retrieve the sampled values by calling the getCachingSamples() method.

If the memory required to cache sampled values is larger than the value specified in the MAX_BUFFER_SIZE constant, this method throws a MemoryError. An IOError is thrown if the device hasn't been enabled before calling this method.

Parameters

	`numSamples:int` — The number of samples to store in the cache. When retrieving samples you always get less than or equal to `numSamples`.

	`controls:Vector.<String>` — A vector of `String`. Each `String` is an id of a control. The samples are written in the same order provided in this vector.

Throws

	`RangeError` — When `numSamples` is less than or equal to zero, or when an entry in `controls` is less than zero or greater than `(numControls - 1)`.

	`ArgumentError` — When controls is `null` or doesn't contain at least one entry or contains invalid enteries.

	`IOError` — When this method is called on a disabled device.

	`MemoryError` — When the cache size `(number of values * samples)` is larger than `MAX_BUFFER_SIZE`.

stopCachingSamples

()

method

public function stopCachingSamples():void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Stops sample caching. Although change events on controls are still dispatched, no more samples are saved in the cache. Values are still retrieved at the frequency specified by sampleInterval, however those values are not stored in the cache. Therefore you can only retrieve the latest value.

Throws

IOError — When you call this method without first enabling the device.

Constant Detail

MAX_BUFFER_SIZE

Constant

public static const MAX_BUFFER_SIZE:int = 32000

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3.7

Specifies the maximum size for the buffer used to cache sampled control values. If startCachingSamples returns samples that require more memory than you specify, it throws a memory error.

GameInputDevice - AS3

Classes x

enabled

id

name

numControls

sampleInterval

getCachedSamples

getControlAt

startCachingSamples

stopCachingSamples

MAX_BUFFER_SIZE

flash.ui GameInputDevice - AS3		Properties \| Properties \| Constructor \| Methods \| Global Constants \| Events \| Styles \| Skin Parts \| Skin States \| Effects \| Constants \| Global Functions \| Functions \| Interfaces \| Classes \| Examples