| Package | flash.ui |
| Class | public final class GameInputDevice |
| Inheritance | GameInputDevice  Object |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3.7 |
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 (
enabledset tofalse). You must explicitly enable a device, by settingenabledtotrue, before you can get control values from the device. -
Get the name and ID of an input device. The
nameandidproperties together uniquely identify a device. For Android devices, the device manufacturer supplies these values. For iOS devices, theidmay change each time you connect the device. -
Enumerate the controls on an input device. Physical controls on a
device are mapped to logical
GameInputControlobjects and stored in a list. You access a control in the list with thegetControlAt()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
valuemethod on theGameInputControlclass, 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
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 | ||
| Method | Defined By | ||
|---|---|---|---|
Writes cached sample values to the ByteArray. | GameInputDevice | ||
Retrieves a specific control from a device. | GameInputDevice | ||
|
Indicates whether an object has a specified property defined. | Object | |
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
|
Indicates whether the specified property exists and is enumerable. | Object | |
|
Sets the availability of a dynamic property for loop operations. | Object | |
Requests this device to start keeping a cache of sampled values. | GameInputDevice | ||
Stops sample caching. | GameInputDevice | ||
|
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
|
Returns the string representation of the specified object. | Object | |
|
Returns the primitive value of the specified object. | Object | |
| Constant | Defined By | ||
|---|---|---|---|
| MAX_BUFFER_SIZE : int = 32000 [static]
Specifies the maximum size for the buffer used to cache sampled
control values. | GameInputDevice | ||
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 |
numControls | property |
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):voidThrows
IOError — When the device is disabled while setting
this property.
| |
RangeError — When the sampleInterval is less than 0.
|
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.
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)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.
|
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.
|
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.
|
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.
Thu Dec 6 2018, 01:12 PM -08:00