View source

final class GameInput

package openfl.ui

extends EventDispatcher

@:directlyUsed@:fileXml("tags=\"haxe,release\"")@:noDebug@:access(openfl.ui.GameInputControl)@:access(openfl.ui.GameInputDevice)@:final

Available on all platforms

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.

Static variables

@:value(true)staticread onlyisSupported:Bool = true

Indicates whether the current platform supports the GameInput API.

@:value(0)staticread onlynumDevices:Int = 0

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

Static methods

staticgetDeviceAt(index:Int):GameInputDevice

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

The index position in the list of input devices.

Returns:

The specified GameInputDevice.

Throws:

RangeError

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

Constructor

new()

Methods

Inherited Variables

Inherited Methods

Defined by EventDispatcher

dispatchEvent(event:Event):Bool

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

Parameters:

event

The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its target property cannot be changed, so you must create a new copy of the event for redispatching to work.

Returns:

A value of true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event.

Throws:

Error

The event dispatch recursion limit has been reached.

hasEventListener(type:String):Bool

Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use willTrigger().

The difference between hasEventListener() and willTrigger() is that hasEventListener() examines only the object to which it belongs, whereas willTrigger() examines the entire event flow for the event specified by the type parameter.

When hasEventListener() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type is registered; false otherwise.

@:value({ useCapture : false })removeEventListener<T>(type:EventType<T>, listener:T ‑> Void, useCapture:Bool = false):Void

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters:

type

The type of event.

useCapture

Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to removeEventListener() are required to remove both, one call with useCapture() set to true, and another call with useCapture() set to false.

toString():String

willTrigger(type:String):Bool

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns true if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

The difference between the hasEventListener() and the willTrigger() methods is that hasEventListener() examines only the object to which it belongs, whereas the willTrigger() method examines the entire event flow for the event specified by the type parameter.

When willTrigger() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type will be triggered; false otherwise.