flash.ui

# GameInputDevice - AS3

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.

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00