enabled:Boolean  [read-write]

Language version:

ActionScript 3.0

Runtime version:

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:String  [read-only]

Language version:

ActionScript 3.0

Runtime version:

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:String  [read-only]

Language version:

ActionScript 3.0

Runtime version:

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:int  [read-only]

Language version:

ActionScript 3.0

Runtime version:

AIR 3.7

Returns the number of controls on this device.

Implementation
    public function get numControls():int

sampleInterval:int  [read-write]

Language version:

ActionScript 3.0

Runtime version:

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

	Error — When the device is disabled while setting this property.
	RangeError — When the sampleInterval is less than 0.

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

Language version:

ActionScript 3.0

Runtime version:

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.
	Error — When this method is called and the device is disabled.

public function getControlAt(i:int):GameInputControl

Language version:

ActionScript 3.0

Runtime version:

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).

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

Language version:

ActionScript 3.0

Runtime version:

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.
	Error — When this method is called on a disabled device.
	Error — When the cache size (number of values * samples) is larger than MAX_BUFFER_SIZE.

public function stopCachingSamples():void

Language version:

ActionScript 3.0

Runtime version:

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

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

public static const MAX_BUFFER_SIZE:int = 32000

Language version:

ActionScript 3.0

Runtime version:

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.