| Package | flash.ui |
| Class | public final class GameInputControl |
| Inheritance | GameInputControl  EventDispatcher Object |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3 |
The simple logical control types are constants defined in the
GameInputControlType class. The logical types include:
- movement
- rotation
- direction
- acceleration
- button
- trigger
type
property.
A physical control on a device
does not always map directly to a single GameInputControl type.
For example, one physical control can be mapped to two logical controls.
Suppose a physical control has rotation properties and movement
properties. The physical control is mapped to two separate logical controls. The
opposite case can occur as well. Multiple physical controls can be mapped
to a single logical control. For example, a thumbstick control can be
considered two controls (an x-axis and y-axis). A thumbstick control is mapped
into a single logical "movement" control with two values.
Getting Control Values
The getValueAt() method returns the current value of a
control. This method does not return the latest value directly from the
control. Instead it returns the value that was cached the last time the
control was sampled.
There are three ways to get control values from an individual control:
-
Polling: Call
getValueAt()whenever you want to get the last known value for a control. -
Change Events: Register a change event for a controller. The
Event.CHANGEevent is dispatched whenever the value of a control changes. Upon receiving the event, callgetValueAt()to get the value for the control that fired the event. -
Caching Sample Values: Caching is done at the device level. See
the
GameInputDeviceclass documentation for details on caching and retrieving sampled control values.
Attempting to read control values from a disabled device causes
getValueAt() to throw an IOError. However, you can
access properties describing a control (such as hand,
index, and relative) even if the device is not
enabled. This feature makes it possible to determine if a device fits the
needs of your application, without having to first enable the device.
Related API Elements
flash.ui.GameInputDevice
flash.ui.GameInputControlType
flash.ui.GameInputHand
flash.ui.GameInputFinger
flash.events.GameInputEvent
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 | |
| device : GameInputDevice [read-only]
Returns the GameInputDevice object that contains this control. | GameInputControl | ||
| finger : String [read-only]
Returns the finger used to operate this control. | GameInputControl | ||
| hand : String [read-only]
Returns the hand used to operate this control. | GameInputControl | ||
| index : int [read-only]
Returns the index position of this GameInputControl
object in the list of controls. | GameInputControl | ||
| numValues : int [read-only]
Provides the number of values that this control has. | GameInputControl | ||
| prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | |
| relative : Boolean [read-only]
Indicates whether the return value is relative to the
previous return value. | GameInputControl | ||
| type : String [read-only]
Returns the type of control. | GameInputControl | ||
| Method | Defined By | ||
|---|---|---|---|
| GameInputControl | |||
| 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 | |
|
Dispatches an event into the event flow. | EventDispatcher | |
Returns the value for this control. | GameInputControl | ||
|
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | |
|
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 | |
|
Removes a listener from the EventDispatcher object. | EventDispatcher | |
|
Sets the availability of a dynamic property for loop operations. | Object | |
|
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 | |
|
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher | |
| Event | Summary | Defined By | ||
|---|---|---|---|---|
| [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher | ||
| [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher | ||
| Dispatched when a control value changes. | GameInputControl | |||
device | property |
device:GameInputDevice [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3 |
Returns the GameInputDevice object that contains this control.
Implementation
public function get device():GameInputDevice finger | property |
finger:String [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3 |
Returns the finger used to operate this control. Hand types are
defined as constants in the GameInputHand class.
This value is optionally provided by the device. If the value
is not provided by default, it is set to
GameInputFinger.UNKNOWN.
Implementation
public function get finger():String hand | property |
hand:String [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3 |
Returns the hand used to operate this control. Hand types are
defined as constants in the GameInputHand class.
This value is optionally provided by the device. If the value
is not provided by default, it is set to GameInputHand.UNKNOWN.
Implementation
public function get hand():String index | property |
numValues | property |
numValues:int [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3 |
Provides the number of values that this control has. Buttons and
triggers have only one value. For an axis control, the number depends
on how many axes the control supports. If the control supports
multiple axes, then the values are arranged in the following order:
x,y,z. There is one value for each axis.
Implementation
public function get numValues():int relative | property |
relative:Boolean [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3 |
Indicates whether the return value is relative to the previous return value. For example, a mouse returns a relative value. As you move a mouse, the value it returns is the change from the previous value.
Implementation
public function get relative():Boolean type | property |
GameInputControl | () | Constructor |
public function GameInputControl()getValueAt | () | method |
public function getValueAt(index:int = 0):Number| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 3 |
Returns the value for this control. If the control returns more than
one value, then you must specify the index of the value you want.
An IOError is thrown if the device is disabled when you
call this method.
Parameters
index:int (default = 0) |
Number — The value requested as a Number.
|
Throws
RangeError — When index is less than 0 or greater than
(numValues - 1).
| |
IOError — When getValueAt() is called while the device is
disabled.
|
Event.CHANGE | Event |
Mon Nov 28 2011, 06:48 AM -08:00