flash.ui

# GameInput - AS3

Package | flash.ui
Class | public final class GameInput
Inheritance | GameInput EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.7

The `GameInput` class is the entry point into the GameInput API. You can use this API to manage the communications between an application and game input devices (for example: joysticks, gamepads, and wands).

The main purpose of this class is to provide access to the supported input devices that are connected to your application platform. This static class enumerates the connected input devices in a list. You access a device from the list using the `getDeviceAt(index:int)` method.

The `numDevices` property provides the number of input devices currently connected to your platform. Use this value to determine the upper bound of the list of devices.

Use an instance of this class to listen for events that notify you about the addition and removal of input devices. To listen these events, do the following:

1. Create an instance of the `GameInput` class.
2. Add event listeners for the `GameInputEvent.DEVICE_ADDED` and `GameInputEvent.DEVICE_REMOVED` events. (Events can only be registered on an instance of the class.)

This class also features the `isSupported` flag, which indicates whether the GameInput API is supported on your platform.

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.

How to Detect One Game Input Device From Among Identical Devices

A common requirement for two-or-more player games is detecting one device from among identical devices. For example, applications sometimes must determine which device represents "Player 1", "Player 2", ..., "Player N".

Solution:

1. Add event listeners to every control on all undetected input devices. These event listeners listen for `Event.CHANGE` events, which are dispatched whenever a control value changes.
2. The first time any control is activated (for example a button press or trigger pull) the application labels that device.
3. Remove all of the event listeners from the remaining undetected input devices.
4. Repeat steps 1-3 as required to identify the rest of the undetected input devices.

Related API Elements

flash.ui.GameInputDevice
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
|  | isSupported : Boolean [static] [read-only] Indicates whether the current platform supports the GameInput API. | GameInput
|  | numDevices : int [static] [read-only] Provides the number of connected input devices. | GameInput

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
|  | getDeviceAt(index:int):GameInputDevice [static] Gets the input device at the specified index location in the list of connected input devices. | GameInput
|  | 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
|  | 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
|  | deviceAdded | Dispatched when a game input device is connected to your platform, or when an already connected device is switched on. | GameInput
|  | deviceRemoved | Dispatched when a game input device is removed from your platform, or when a connected device is switched off. | GameInput
|  | deviceUnusable | Dispatched when a game input device is connected but is not usable. | GameInput

Property Detail

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.7

Indicates whether the current platform supports the GameInput API.

Implementation
`public static function get isSupported():Boolean`

### numDevices

property

`numDevices:int` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.7

Provides the number of connected input devices. When a device is connected, the `GameInputEvent.DEVICE_ADDED` event is fired.

Implementation
`public static function get numDevices():int`
Method Detail

### getDeviceAt

()
method

`public static function getDeviceAt(index:int):GameInputDevice`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.7

Gets the input device at the specified index location in the list of connected input devices.

The order of devices in the index may change whenever a device is added or removed. You can check the `name` and `id` properties on a `GameInputDevice` object to match a specific input device.

Parameters

| `index:int` — The index position in the list of input devices.

Returns

| `GameInputDevice` — The specified `GameInputDevice`.

Throws

| `RangeError` — When the provided index is less than zero or greater than `(numDevices - 1)`.

Event Detail

### deviceAdded

Event

Event Object Type: `flash.events.GameInputEvent`

Dispatched when a game input device is connected to your platform, or when an already connected device is switched on.

### deviceRemoved

Event

Event Object Type: `flash.events.GameInputEvent`

Dispatched when a game input device is removed from your platform, or when a connected device is switched off.

### deviceUnusable

Event

Event Object Type: `flash.events.GameInputEvent`

Dispatched when a game input device is connected but is not usable. This event is specific to Windows only. For example, this happens in a Windows sandboxed browser when another DirectInput based application is already using the device.

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