键盘操作 §

键盘按键 §

Keyboard 类中定义了下面罗列的键位常量。需要注意，这些常量并不代表字母或特定的字符串，而代表键盘上的键位。

每个键盘按键均对应一个扫描码（scan code）。扫描码被操作系统获取后，根据操作系统中的键盘布局设置（如中国大陆地区采用的美式键盘布局）解释为相应的虚拟按键（virtual key）。例如，按下美式 QWERTY 布局键盘上的 Q 键后，键盘向操作系统发送一个扫描码，若操作系统的键盘布局为法国 AZERTY 布局，则这个扫描码会被映射到虚拟按键 A。因此，键盘上的“按键名称”并不代表真实的按键，而是对应于某一个扫描码，按下某个特定按键，都会向操作系统发送这个扫描码。对该扫描码的解释方法由操作系统确定。

在罗列下面的键位常量时，遵循美式 QWERTY 键盘布局进行说明，并假定用户的操作系统虚拟按键布局同为美式 QWERTY 键盘布局。

unreleased §

说明：已通过 press 按下，但未通过 release 或 reset 弹起的按键，类型为 { string | boolean |nil }。当某个按键通过 press 按下，则在此表中该按键状态被记录为 true；后续若通过 release 弹起，则记录为 nil。

frozen §

说明：键盘是否处于冻结状态，类型为 boolean。

注解：冻结状态下，Keyboard 提供的除 reset 外所有键盘操作接口失效。

freeze §

说明：冻结键盘，冻结后所有的键盘操作（reset 除外）将被忽略。

原型：Keyboard:freeze()

unfreeze §

说明：与 freeze 相对，解除键盘冻结状态。

原型：Keyboard:unfreeze()

is_frozen §

说明：判断键盘是否冻结。

原型：Keyboard:is_frozen()

返回：若处于冻结状态，返回 true；否则，返回 false。

is_key_name_valid §

说明：判断给定的按键名称是否有效（即在 键盘按键 列出的键位中）。

原型：Keyboard:is_key_name_valid(key_name)

• key_name：待检查的按键名称，类型为 any。

返回：若按键有效，返回 true；否则，返回 false。

press §

说明：按下一个或多个按键。

原型：Keyboard:press(key, delay, precise)

• key：需要按下的按键或按键列表，类型为 string | string[]。可以为单个按键（如：Keyboard.ESCAPE），也可以为若干按键形成的列表，如 { Keyboard.A, Keyboard.B, Keyboard.C }。
• delay：按下按键后的延迟时间，类型为 integer | nil，单位为毫秒，缺省值为 50。
• precise：延迟时间是否需要精确定时，类型为 boolean | nil。

注解：调用该接口按下某个按键后，将在 unreleased 表中记录按下的按键。

release §

说明：弹起一个或多个按键。

原型：Keyboard:release(key, delay, precise)

• key：需要弹起的按键或按键列表，类型为 string | string[]。可以为单个按键（如：Keyboard.ESCAPE），也可以为若干按键形成的列表，如 { Keyboard.A, Keyboard.B, Keyboard.C }。
• delay：弹起按键后的延迟时间，类型为 integer | nil，单位为毫秒，缺省值为 50。
• precise：延迟时间是否需要精确定时，类型为 boolean | nil。

注解：调用该接口弹起某个按键后，将在 unreleased 表中移除（若存在）该按键。

click §

说明：敲击（按下并弹起）某个按键。

原型：Keyboard:click(key, delay, precise)

• key：需要敲击的按键或按键列表，类型为 string | string[]。可以为单个按键（如：Keyboard.ESCAPE），也可以为若干按键形成的列表，如 { Keyboard.A, Keyboard.B, Keyboard.C }。
• delay：敲击按键后的延迟时间，类型为 integer | nil，单位为毫秒，缺省值为 50。
• precise：延迟时间是否需要精确定时，类型为 boolean | nil。

click_several_times §

说明：敲击（按下并弹起）指定按键若干次。

原型：Keyboard:click_several_times(key, times, interval, delay, precise)

• key：需要敲击的按键或按键列表，类型为 string | string[]。可以为单个按键（如：Keyboard.ESCAPE），也可以为若干按键形成的列表，如 { Keyboard.A, Keyboard.B, Keyboard.C }。
• times：重复次数，类型为 integer | nil，缺省值为 0。
• interval：敲击间隔时间，类型为 integer | nil，单位为毫秒（最后一次敲击后不适用该间隔时间），缺省值为 50。
• delay：敲击按键后的延迟时间，类型为 integer | nil，单位为毫秒，缺省值为 50。
• precise：延迟时间是否需要精确定时，类型为 boolean | nil。

reset §

说明：重置键盘，即弹起 unreleased 中记录的所有按键。

原型：Keyboard:reset()

注解：该接口不受 frozen 影响。

puts §

说明：通过键盘输入由字母和数字构成的字符串。

原型：Keyboard:puts(s)

• s：待输入的字符串，类型为 string。

注解：s 中非字母和数字的内容将被忽略。

is_modifier_pressed §

说明：判断修饰键是否被按下。

原型：Keyboard:is_modifier_pressed(modifier)

• modifier：修饰键，包括 Keyboard.LEFT_SHIFT、Keyboard.RIGHT_SHIFT、Keyboard.LEFT_CTRL、Keyboard.RIGHT_CTRL、Keyboard.LEFT_ALT、Keyboard.RIGHT_ALT。

返回：若指定的修饰键被按下，则返回 true；否则，返回 false。

注解：若不关心修饰键的左右之分，可使用下列值（注意：仅限此接口中使用）。