GameInputDevice - Adobe ActionScript® 3 (AS3 ) API 参考

包	flash.ui
类	public final class GameInputDevice
继承	GameInputDevice Object

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

GameInputDevice 类表示常用于游戏的单个输入设备。

此类包含可用于执行以下操作的方法和属性：

启用或禁用某个输入设备。默认情况下最初禁用设备（enabled 设置为 false）。必须明确启用某个设备（通过将 enabled 设置为 true），才能从该设备获取控制值。
获取输入设备的名称和 ID。name 和 id 属性一起唯一标识一个设备。对于 Android 设备，设备制造商会提供这些值。对于 iOS 设备，id 可能会在每次连接设备时发生改变。
枚举输入设备上的控件。设备上的物理控件被映射到逻辑 GameInputControl 对象中并存储在列表中。使用 getControlAt() 方法可访问列表中的控件。
管理取样控件值的缓存。直接从设备对象取样一组控件值是获取控件值的三种方法之一。（另外两种方法在 GameInputControl 类中使用 value 方法，此类中对这两种方法进行了介绍。）当需要以高于应用程序帧速率的速率访问控件值时，样本缓存十分有用。

始终在此类上为 GameInputEvent.DEVICE_REMOVED 事件设置侦听器。使用此侦听器可以处理设备意外断开或关闭的情况。当某个设备断开时，释放其 GameInputDevice 对象，因为在其关联设备断开后此对象不再有效。

删除后重新连接的 Android 设备会保留其在首次连接时拥有的 ID。通过匹配设备 ID 可以从逻辑上重新连接到该设备。对于 iOS 设备，ID 可能会在每次重新连接设备时发生改变。

注意：不能依赖列表中设备的顺序。（当添加和删除设备时，顺序会发生改变。）

有关更多信息，请参阅 Adobe AIR 开发人员中心文章：Adobe AIR 中的游戏控制器。

对于 Android，此功能支持的 Android OS 最低版本为 4.1，需要的 SWF 最低版本为 20，命名空间最低版本为 3.7。对于 iOS，此功能支持的 iOS 最低版本为 9.0，需要的 SWF 最低版本为 34，命名空间最低版本为 23.0。

	属性	由以下参数定义
		constructor : Object 对类对象或给定对象实例的构造函数的引用。	Object
		enabled : Boolean 启用或禁用此设备。	GameInputDevice
		id : String [只读] 返回此设备的 ID。	GameInputDevice
		name : String [只读] 返回此设备的名称。	GameInputDevice
		numControls : int [只读] 返回此设备上的控件数量。	GameInputDevice
		sampleInterval : int 指定检索控件值的速率（以毫秒为单位）。	GameInputDevice

	方法	由以下参数定义
		getCachedSamples(data:ByteArray, append:Boolean = false):int 将缓存的样本值写入 ByteArray。	GameInputDevice
		getControlAt(i:int):GameInputControl 从某个设备检索特定控件。	GameInputDevice
		hasOwnProperty(name:String):Boolean 表示对象是否已经定义了指定的属性。	Object
		isPrototypeOf(theClass:Object):Boolean 表示 Object 类的实例是否在指定为参数的对象的原型链中。	Object
		propertyIsEnumerable(name:String):Boolean 表示指定的属性是否存在、是否可枚举。	Object
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 设置循环操作动态属性的可用性。	Object
		startCachingSamples(numSamples:int, controls:Vector.<String>):void 请求此设备开始保留取样值的缓存。	GameInputDevice
		stopCachingSamples():void 停止样本缓存。	GameInputDevice
		toLocaleString():String 返回此对象的字符串表示形式，其格式设置遵守区域设置特定的约定。	Object
		toString():String 返回指定对象的字符串表示形式。	Object
		valueOf():Object 返回指定对象的原始值。	Object

	常量	由以下参数定义
		MAX_BUFFER_SIZE : int = 32000 [静态] 指定用于缓存取样控件值的缓冲区的最大大小。	GameInputDevice

enabled

属性

enabled:Boolean

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

启用或禁用此设备。默认情况下禁用设备。请启用设备以访问或取样其控件值。此外，仅当启用设备时，设备及其单个控件才会调度事件。

在删除某个设备时，将禁用该设备。您仍可获取有关已禁用设备的信息，但无法访问控件值或启动缓存。此外，如果已删除该设备，则无法再启用它。如果删除了某个设备，enabled 始终返回 false。

实现
public function get enabled():Boolean
public function set enabled(value:Boolean):void

id

属性

id:String [只读]

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

返回此设备的 ID。可通过 ID 区分设备。

注意：对于 Android 设备，设备制造商会提供设备 ID。对于 iOS 设备，ID 可能会在每次重新连接设备时发生改变。

实现
public function get id():String

name

属性

name:String [只读]

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

返回此设备的名称。名称可帮助识别设备的类型。

注意：设备制造商提供了其设备的名称。

实现
public function get name():String

numControls

属性

numControls:int [只读]

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

返回此设备上的控件数量。

实现
public function get numControls():int

sampleInterval

属性

sampleInterval:int

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

指定检索控件值的速率（以毫秒为单位）。默认值为 0，这表示每个帧更新一次值。设置更高的 sampleValue 会指示 GameInput 以高于应用程序帧速率的速率取样控件值。

尽管值的更新频率可以高于每个帧一次，但每个控件仅调度一个事件。因此，如果一个帧中出现对某个值的两次更新，则只会调度一个更改事件，并且只能检索到最新的值。

要不仅仅检索最新的值，可使用此类中的缓存方法缓存样本值。当缓存取样值时，此属性确定将值写入缓存中的频率。

默认值为 0。

实现
public function get sampleInterval():int
public function set sampleInterval(value:int):void

引发

	`IOError` — 设置此属性时如果禁用设备。

	`RangeError` — 当 `sampleInterval` 小于 0 时。

方法详细信息

getCachedSamples

()

方法

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

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

将缓存的样本值写入 ByteArray。缓存的样本值按检索顺序（最早检索的值先写入，最新检索的值后写入）写入 ByteArray 中。

此方法返回写入 ByteArray 中的缓存样本值数量（而不是值本身）。如果 append 参数为 false（默认值），则会在从缓存中写入样本值之前清除 ByteArray。如果 append 为 true，则会将样本值追加到 ByteArray，而保留以前的值。在以下情况下，追加样本值：

必须保持特定数量的值可用时。
必须保留大于缓存的历史记录时。

重要说明：如果 append 为 true，则应用程序负责清除 ByteArray。如果未清除 ByteArray，它会继续增大，从而可能导致应用程序崩溃。

在将样本值写入 ByteArray 之后会清除缓存。

如果调用此方法时禁用了设备，则会引发 IOError。

参数

	`data:ByteArray` — 保存所检索到数据的 ByteArray。该数组使用以双精度值写入的样本值进行填充。如果在控件的位置未检测到更改，则 ByteArray 将 NaN 作为控件的值来保存。

	`append:Boolean` (default = `false`) — 确定如何将数据写入 `ByteArray` 中的标记。如果值为 `true`，会将取样值写入数组的末尾。如果为 `false`，则删除 `ByteArray` 的内容，然后将数据写入数组中。默认值为 `false`。

int — 写入 ByteArray 的样本（而不是值）数量。

引发

	`ArgumentError` — 当 `data` 为 null 时。

	`IOError` — 当调用此方法且禁用设备时。

getControlAt

()

方法

public function getControlAt(i:int):GameInputControl

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

从某个设备检索特定控件。

GameInputDevice 将设备上的控件存储在列表中。可以使用 getControlAt() 方法访问设备上的个别控件。

每当添加或删除设备时，索引中控件的顺序可能会改变。您可以检查 GameInputControl 对象的 id 属性，确定是哪个特定的控件。

即使未启用设备也可获取控件。不过，无法从禁用的设备读取控件值。使用此功能可以在启用控件所属的设备前读取其属性。您可使用此功能在启用某个设备前确定该设备是否适合您的应用程序。

参数

i:int — GameInputControl 在 GameInputControl 列表中的索引位置。

GameInputControl — 指定索引位置的 GameInputControl 对象。

引发

RangeError — 当索引小于零或大于 (numControls - 1) 时。

startCachingSamples

()

方法

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

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

请求此设备开始保留取样值的缓存。sampleInterval 属性确定取样的频率。numSamples 参数指定要缓存的样本数。controls 参数指定要取样的控件的 ID 值。

控件值按指定顺序缓存。通过调用 getCachingSamples() 方法可检索取样值。

如果缓存取样值所需的内存大于 MAX_BUFFER_SIZE 常量指定的值，则此方法会引发 MemoryError。如果在调用此方法之前尚未启用设备，则会引发 IOError。

参数

	`numSamples:int` — 缓存中要存储的样本数。检索样本时，始终获得小于或等于 `numSamples`。

	`controls:Vector.<String>` — `String` 的矢量。每个 `String` 是一个控件的 id。样本的写入顺序与此矢量中提供的顺序相同。

引发

	`RangeError` — 当 `numSamples` 小于或等于零时，或当 `controls` 中的某个条目小于零或大于 `(numControls - 1)` 时。

	`ArgumentError` — 当控件为 `null` 时，或者不包含任何项或包含的项无效时。

	`IOError` — 当对禁用的设备调用此方法时。

	`MemoryError` — 当缓存大小`(number of values * samples)` 大于 `MAX_BUFFER_SIZE` 时。

stopCachingSamples

()

方法

public function stopCachingSamples():void

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

停止样本缓存。尽管仍调度控件上的更改事件，但不会在缓存中保存样本。仍以 sampleInterval 指定的频率检索值，不过不会在缓存中存储这些值。因此，只能检索到最新的值。

引发

IOError — 不先启用设备就调用此方法时。

常量详细信息

MAX_BUFFER_SIZE

常量

public static const MAX_BUFFER_SIZE:int = 32000

语言版本:

ActionScript 3.0

运行时版本:

AIR 3.7

指定用于缓存取样控件值的缓冲区的最大大小。如果 startCachingSamples 返回的样本所需的内存大于指定的内存，则会引发内存错误。

法律声明 | 在线隐私策略

GameInputDevice - AS3

类 x

enabled

id

name

numControls

sampleInterval

getCachedSamples

getControlAt

startCachingSamples

stopCachingSamples

MAX_BUFFER_SIZE