138 lines
2.9 KiB
Markdown
138 lines
2.9 KiB
Markdown
# KEYBOARD
|
|
|
|
The built-in object representing keyboard state. Available under the global name `KEYBOARD` from any context (see [Built-in objects](../engine/globals.md#built-in-objects)). Handles key-down and key-up events, including auto-repeat mode.
|
|
|
|
## Methods
|
|
|
|
### DISABLE
|
|
|
|
```
|
|
void DISABLE()
|
|
```
|
|
|
|
Disables keyboard event handling — key signals stop being fired.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
KEYBOARD^DISABLE();
|
|
```
|
|
|
|
### ENABLE
|
|
|
|
```
|
|
void ENABLE()
|
|
```
|
|
|
|
Enables keyboard event handling.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
KEYBOARD^ENABLE();
|
|
```
|
|
|
|
### GETLATESTKEY
|
|
|
|
```
|
|
STRING GETLATESTKEY()
|
|
```
|
|
|
|
Returns the name of the most recently pressed key.
|
|
|
|
**Returns**: the key name in the format accepted by [`ISKEYDOWN`](#iskeydown) (see [Supported keys](#supported-keys)).
|
|
|
|
**Examples**
|
|
|
|
```
|
|
KEYBOARD^GETLATESTKEY();
|
|
```
|
|
|
|
### ISENABLED
|
|
|
|
```
|
|
BOOL ISENABLED()
|
|
```
|
|
|
|
Checks whether keyboard handling is enabled.
|
|
|
|
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the keyboard is responding to events.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
KEYBOARD^ISENABLED();
|
|
```
|
|
|
|
### ISKEYDOWN
|
|
|
|
```
|
|
BOOL ISKEYDOWN(STRING keyName)
|
|
```
|
|
|
|
Checks whether the given key is currently held down.
|
|
|
|
**Parameters**
|
|
|
|
- `keyName` — the key name (see [Supported keys](#supported-keys)).
|
|
|
|
**Returns**: [`BOOL`](BOOL.md) — `TRUE` if the key is held down. For an unknown key name, `FALSE` is returned.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
KEYBOARD^ISKEYDOWN("UP");
|
|
KEYBOARD^ISKEYDOWN("LEFT");
|
|
KEYBOARD^ISKEYDOWN(ARRAYKEYBOARD^GET(0));
|
|
```
|
|
|
|
### SETAUTOREPEAT
|
|
|
|
```
|
|
void SETAUTOREPEAT(BOOL autorepeat)
|
|
```
|
|
|
|
Sets whether the [`ONKEYDOWN`](#onkeydown) signal is fired repeatedly as long as the key remains held down. Disabled by default.
|
|
|
|
**Parameters**
|
|
|
|
- `autorepeat` — `TRUE` to enable repeat firing.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
KEYBOARD^SETAUTOREPEAT(FALSE);
|
|
```
|
|
|
|
## Signals
|
|
|
|
### ONKEYDOWN
|
|
|
|
Fired when a key is pressed. The signal is [parameterised](../engine/events.md#parameterised-signals) by the key name — separate handlers can be attached for each:
|
|
|
|
```
|
|
KEYBOARD:ONKEYDOWN^UP=BEHGOUP
|
|
KEYBOARD:ONKEYDOWN^DOWN=BEHGODOWN
|
|
```
|
|
|
|
When auto-repeat is enabled ([`SETAUTOREPEAT(TRUE)`](#setautorepeat)), the signal is fired on every frame in which the key remains held down.
|
|
|
|
### ONKEYUP
|
|
|
|
Fired when a key is released. The signal is parameterised by the key name, analogously to [`ONKEYDOWN`](#onkeydown).
|
|
|
|
### ONCHAR
|
|
|
|
Fired for every character produced by a keypress. The signal is parameterised by the key name.
|
|
|
|
## Supported keys
|
|
|
|
The engine's keyboard recognises the following key names:
|
|
|
|
- **Function keys**: `F1`, `F2`, `F3`, `F4`, `F5`, `F6`, `F7`, `F8`, `F9`, `F10`, `F11`, `F12`
|
|
- **Arrows**: `UP`, `DOWN`, `LEFT`, `RIGHT`
|
|
- **Modifiers**: `LSHIFT`, `RSHIFT`, `LCTRL`, `RCTRL`, `LALT`, `RALT`, `CAPSLOCK`
|
|
- **Special**: `ESC`, `ENTER`, `SPACE`, `TAB`, `INSERT`, `PGUP`, `PGDN`, `HOME`
|
|
- **Letters**: `Q`, `W`, `E`, `R`, `T`, `U`, `I`, `O`, `P`, `A`, `S`, `D`, `F`, `G`, `H`, `J`, `K`, `L`, `C`, `V`, `B`, `N`, `M`
|
|
- **Digits**: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`
|