flash.ui.GameInputDevice - ActionScript® 3.0 Reference for the Adobe® Flash® Platform

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

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3

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. The device manufacturer supplies these values.
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 getValueAt() 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.

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

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

Related API Elements

flash.ui.GameInput
flash.ui.GameInputControl
flash.ui.GameInputControlType
flash.ui.GameInputHand
flash.ui.GameInputFinger
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
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		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
		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
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		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
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		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
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		startCachingSamples(numSamples:int, controls:Vector.<int>):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
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher

Events

Click for more information on events

Hide Inherited Events

Show Inherited Events

	Event		Summary	Defined By
		activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
		deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher

Public Constants

	Constant		Defined By
		MAX_BUFFER_SIZE : int = 4800 [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

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

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

Note: The device manufacturer provides device IDs.

Implementation
public function get id():String

name

property

name:String [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3

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

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

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

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 which holds the retrieved data. It is filled with sample values written as floats.

	`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. By default `append` 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

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 index position of the controls in the list does not change.

Sometimes a control is not supported. In this case, the unsupported control does not show up in the list of controls. Also, some physical controls are combined into a single logical control. For example, a thumbstick can have two physical controls (an x-axis and y-axis). The GameInput API combines the physical controls into a single movement control with two values.

You can get controls even if a device is not enabled. However you cannot read control values from a disabled device. This feature allows you to 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.<int>):void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3

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.<int>` — A vector of `ints`. Each `int` is an index to 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.

	`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

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 = 4800

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 3

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.

[an error occurred while processing this directive]

Legal Notices | Online Privacy Policy

Classes x

enabled

id

name

numControls

sampleInterval

getCachedSamples

getControlAt

startCachingSamples

stopCachingSamples

MAX_BUFFER_SIZE