Keyboard
Generated from engine/input/keyboard.h at aceb130. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: game code.
#include "engine/input/keyboard.h" · namespace labrador
The shell feeds key and decoded-text events; poll() latches them into frame snapshots. Typed characters are a separate channel because key state cannot reconstruct the platform's text input.
enum class Key
Section titled “enum class Key”{ none = 0,
a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z,
digit_0, digit_1, digit_2, digit_3, digit_4, digit_5, digit_6, digit_7, digit_8, digit_9,
f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12,
escape, tab, caps_lock, shift, control, alt, space, enter, backspace,
insert, del, home, end, page_up, page_down,
left, right, up, down,
print_screen, scroll_lock, pause, num_lock,
minus, equals, left_bracket, right_bracket, backslash, semicolon, apostrophe, grave, comma, period, slash,
numpad_0, numpad_1, numpad_2, numpad_3, numpad_4, numpad_5, numpad_6, numpad_7, numpad_8, numpad_9, numpad_add, numpad_subtract, numpad_multiply, numpad_divide, numpad_decimal,
international_backslash,
count,};Every key this engine names, one bit each in KeyboardState.
It is a key POSITION, not a character. Key::z is the key a US layout calls Z, whatever a French layout prints on it, because that is what a movement binding wants. What was typed is typed(), which is the other question and has the other answer.
Left and right modifiers are combined: shift, control and alt each mean either side (T3). Numpad Enter also reports as enter.
none = 0-
Not a key; the result of an unmapped platform code.
digit_0, digit_1, digit_2, digit_3, digit_4, digit_5, digit_6, digit_7, digit_8, digit_9-
Number-row positions, separate from the numpad.
del, home, end, page_up, page_down-
deleteis a keyword, and this is the one name in the set that could not be spelt the obvious way. international_backslash-
The ISO extra position between left Shift and Z, independent of its printed character: IntlBackslash in a browser, non-extended set-1 scan 0x56 (the OEM extra key) on Win32.
count-
Exclusive bound, not a key.
key_name
Section titled “key_name”The token for a key in a file or a console: the enumerator's own spelling ("a", "digit_1", "numpad_1", "page_up", "left_bracket", "del"). Lower-case ASCII, unique per key, independent of layout and platform. Empty for Key::none, Key::count and any value outside the set. A name, not a label: what a player is shown is the game's. Read at load, not per frame (T7).
Saved bindings use these spellings as file-format tokens; additions preserve existing tokens and their meaning.
key_from_name
Section titled “key_from_name”The key a token names. Exact and case-sensitive: no trimming, no aliases, no chords. Nothing for anything else, "none" and "count" included; the caller decides whether that is a default or an error, as colour_from_name does.
struct KeyboardState
Section titled “struct KeyboardState”One frame's keyboard snapshot. Values may be constructed for edge queries.
focused
Section titled “focused”bool focused = false;False means the window did not have the keyboard this frame. The shell clears held keys on focus loss so snapshots do not retain them.
uint64_t keys[2] = {};One bit per Key, indexed by the enumerator; capacity is checked below.
is_down
Section titled “is_down”Tests the bit without consulting focused. False for Key::none, Key::count and values outside the key set.
pressed · released
Section titled “pressed · released”bool released(const KeyboardState& now, const KeyboardState& before, Key key);Edges between two snapshots. pressed and released require focused on both frames, suppressing key edges on initial focus, focus return and focus loss. A hand-written snapshot must set focused to participate in edges.
A key held when focus is lost produces neither released() nor held(). To stop an action on that transition, query the focus change:
Edges belong to individual keys. OR-ing their pressed() values can fire again while another key remains held. A game wanting one combined edge compares the combined held levels across frames (T1).
just_focused · just_unfocused
Section titled “just_focused · just_unfocused”bool just_unfocused(const KeyboardState& now, const KeyboardState& before);class Keyboard
Section titled “class Keyboard”Current and previous keyboard snapshots, their edges and accumulated text. A game borrows Application::keyboard(); the shell owns it, feeds events and polls once per fixed update before that update's states run. Games read those snapshots without advancing them.
on_key_down · on_key_up
Section titled “on_key_down · on_key_up”void on_key_up(Key key);For the shell or an input fixture. Changes become visible at poll(). A key pressed and released between polls has no sampled edge. Repeated key-down events do not add presses; text accumulates separately. Key::none, Key::count and values outside the key set are ignored.
on_text
Section titled “on_text”void on_text(char32_t codepoint);Appends one decoded Unicode code point for the next poll(), encoded as UTF-8. The platform translator assembles UTF-16 surrogate pairs. Isolated surrogates and values above U+10FFFF become U+FFFD, matching engine/render/text_encoding.h's replacement rule.
C0 controls below U+0020 and U+007F are dropped. Query Enter, Tab, Escape and Backspace as keys rather than appending them to text.
on_key_label · on_key_labels_invalidated
Section titled “on_key_label · on_key_labels_invalidated”void on_key_labels_invalidated();Copies a best-effort display label supplied by the shell or a fixture. A nonempty label must be well-formed UTF-8; input does not decode, normalise or infer it from typed text. Empty means unavailable. Key::none, Key::count and out-of-range values are ignored. Changes are staged until poll(), including explicit invalidation of the complete label map. The shell owns when layout facts expire.
set_focused
Section titled “set_focused”void set_focused(bool focused);Updates focus for the next poll(). Losing focus clears held keys and pending text; regaining it does not restore prior keys. Published snapshots and typed() remain unchanged until poll().
void poll();Called by the shell once per fixed update before readers. Current becomes previous, fed key/focus state becomes current, and accumulated text replaces the text accumulated before the previous poll. Staged labels publish together; only a changed label map advances label_revision().
state · previous_state
Section titled “state · previous_state”const KeyboardState& previous_state() const;Borrowed snapshots owned by this Keyboard; poll() replaces their values.
held · pressed · released
Section titled “held · pressed · released”bool pressed(Key key) const;bool released(Key key) const;focused · just_focused · just_unfocused
Section titled “focused · just_focused · just_unfocused”bool focused() const;bool just_focused() const;bool just_unfocused() const;std::string_view typed() const;Text published by the last poll(), in arrival order as UTF-8. The returned view borrows this object's storage until the next poll() or destruction; copy it to retain text longer. This is fed text, not a reconstruction from key bits or a promise of platform IME support.
A best-effort label for this physical position, not a saved binding token or a promise that the platform reveals its active layout. Unseen, unavailable and invalid keys return nullopt. The UTF-8 view borrows this Keyboard's storage until the next poll() or destruction; feeds and invalidation do not change the currently published view. The game owns conversion to its rendering text, font support and a stable key_name fallback. Labels never change a key's identity.
label_revision
Section titled “label_revision”uint64_t label_revision() const;Starts at zero. Advances once per poll whose published label map differs, including labels becoming unavailable. Repeated facts and invalidation followed by the same complete map do not advance it. Focus changes alone do not invalidate labels.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
samples/audio/audio_state.cppsamples/collision/collision_state.cpp,outlines_state_tests.cppsamples/components/binding_row.h,binding_row_tests.cpp,gallery_animation_tests.cpp,gallery_binding.cpp,gallery_binding_tests.cpp,gallery_bindings.h,gallery_pointer_tests.cpp,gallery_state.cpp,gallery_text.cpp,gallery_text_tests.cpp,gallery_touch_tests.cpp,touch_demo_state.cppsamples/linesweeper/states/pause_state.cpp,play_state.cppsamples/linesweeper/web/test_input.cppsamples/local_multiplayer/controls.h,join_state.cppsamples/minimal/states/confirm_state.cpp,hello_state.cpptests/app/keyboard_input_tests.cpp,startup_child.cpptests/input/keyboard_tests.cpptests/linesweeper/focus_pause_tests.cpp,touch_pause_tests.cpptests/local_multiplayer/join_state_tests.cpptests/minimal/close_request_tests.cpp,state_tests.cpp
Explained in
Section titled “Explained in”- Read your starter's C++
- Input
- Local multiplayer
- Update your code for a newer Labrador
- Copy keyboard rebinding into your game
- Test your game
- Copy the components into your game
- Add a second level
- Make a title menu
- Roll a die in your game
- Add a rule and a test
- Add a screen to your game
- Save settings in your game
- Play sounds from an XWB bank
- Play a sound in your game
- Two players in your game
- Colours, the window and the background
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.