Copy keyboard rebinding into your game
Bindings belong to your game. The components gallery demonstrates a small keyboard table and one capture row, using the existing keyboard state and stable key tokens. It does not add an engine action map or change gamepad bindings.
Try the example
Section titled “Try the example”Run the gallery as Run the samples shows. The original settings and Quit rows remain in place. The Rebind key row follows Quit; Left or Right chooses Restart or Reset difficulty. Enter, Space, gamepad A or a click begins capture. Release the opener and every held key, then press one new key.
Up/Down follows the page’s reading order: the original settings and Quit, then Rebind key, then Name, wrapping at either end. The two final rows sit beside each other, so the page sets that order explicitly instead of relying on their screen geometry.
The gallery allows letter and number-row positions only. Navigation, confirmation, cancellation, reset and other keys stay protected. A duplicate leaves both assignments alone and gives a message; release it before trying another. Escape or gamepad B cancels capture without quitting, and choosing another row with the pointer cancels first. Outside capture, the original Escape/B quit route remains available.
On the idle binding row, Backspace resets both defaults: r restarts the previews and d
resets the difficulty example to Normal. The key that commits a binding does not also run its
action; it needs a fresh press. A key held after that press does not repeatedly fire. Name
editing owns its letters separately, so typing an action key there does not affect the settings
or previews behind the editor.
Take the code
Section titled “Take the code”Copy binding_row.h/.cpp and gallery_bindings.h/.cpp from
samples/components, change their namespace
and includes, and list each .cpp in your game’s CMake target. The row needs the engine’s UI
widgets and a loaded font, as the other copied components do.
Its tests can be copied into an engine-linked test target too.
GalleryBindings is the example’s policy, with exactly two actions. Change its action names,
default keys and allowed/protected set for your own screen. A duplicate is refused instead of
moving another action:
{ const std::size_t index = action_index(action); if (!assignable(key)) return BindingResult::protected_key; if (this->keys_[index] == key) return BindingResult::unchanged; const std::size_t other = 1 - index; if (this->keys_[other] == key) return BindingResult::duplicate; this->keys_[index] = key; return BindingResult::changed;samples/components/gallery_bindings.cpp, lines 33–41 at aceb130
The page asks its keyboard whether the assigned position was pressed. It owns how that action
changes the game; the row never polls a device or interprets typed characters as physical keys.
The gallery’s wiring is in
gallery_binding.cpp and
gallery_state.cpp.
Capture without losing the menu
Section titled “Capture without losing the menu”Pass current and previous KeyboardState values to BindingRow::update_capture. Starting
capture, and every refused candidate, waits for an entirely released snapshot before taking
another edge. Two or more new keys in one snapshot are ambiguous and produce no candidate.
Keyboard focus loss cancels; the gallery also cancels from on_deactivated().
The page handles cancel before candidates, validates a candidate through its own table, and keeps navigation/quit keys out of that table. While either capture or text editing owns a tick, ordinary menu actions and rebound shortcuts are suppressed. A mode-exit tick cancels pending pointer completion as well: a release arriving with Escape or the committing key cannot immediately reopen the editor. Keep those rules when you adapt the example.
Tokens and saved data
Section titled “Tokens and saved data”The table’s tokens() uses key_name, and load_tokens() parses the exact identities with
key_from_name. A whole pair is validated before either value changes; invalid tokens,
protected keys and duplicate values preserve the old table. A valid complete pair may swap
its two distinct keys. The data token is a stable fallback, independent of what the
active keyboard layout prints on that position; see Input.
The gallery saves nothing. Your game chooses whether to persist a table, its format, and how to recover a bad or old file. Keep menu cancellation and a reset route usable after every refusal. Controller rebinding is a separate mechanism.
Show best-effort layout labels
Section titled “Show best-effort layout labels”The gallery’s selected row can show a layout label while its binding remains a physical
position. The separate Label / token line says which text was used and whether the page
fell back because the label was unavailable, unsupported by its font, or too wide. A label
such as q for the position saved as r never makes the Q position run that action.
Keyboard::label(key) returns an optional UTF-8 view. It borrows the keyboard’s storage until
the next poll or destruction, so the page converts or copies it during update(). A label
change or invalidation advances label_revision() when published at an input poll; unchanged
facts do not advance it. Refresh cached display text on that revision and whenever the selected
binding changes. Keep key_name/key_from_name for every data representation.
Copy binding_label.h/.cpp for the gallery’s presentation policy as well. It converts through
the existing widen boundary and checks RenderResources::can_render and measured width before
using a label. The supplied font must always be able to draw the stable token within the row;
a stand-in glyph does not make a missing layout label supported. The gallery’s delivered font
is ASCII only, so an available accented label deliberately displays its token instead. The
helper bounds label conversion to 256 bytes; the gallery reserves 120 units for the key text.
BindingKeyLabel binding_key_label(std::optional<std::string_view> label, labrador::FontHandle font, float max_width){ if (!std::isfinite(max_width) || max_width <= 0.0f || !printable_token(stable_token)) { throw std::invalid_argument("Binding label needs a positive finite width and a printable ASCII token."); } if (!resources.can_render(font, fallback) || resources.measure_text(font, fallback).x > max_width) { throw std::invalid_argument("Binding label font/width cannot show its stable-token fallback."); } if (!label.has_value() || label->empty()) { return { std::move(fallback), BindingLabelSource::token_unavailable }; } if (label->size() > max_label_bytes) { return { std::move(fallback), BindingLabelSource::token_width }; } std::wstring wide = labrador::widen(*label); !resources.can_render(font, wide)) { return { std::move(fallback), BindingLabelSource::token_font }; } if (resources.measure_text(font, wide).x > max_width) { return { std::move(fallback), BindingLabelSource::token_width }; } return { std::move(wide), BindingLabelSource::layout };samples/components/binding_label.cpp, lines 52–85 at aceb130
On Windows, the shell queries the current thread’s input layout, caching labels until the
layout changes or the window activates again. Character queries use a neutral modifier state
and ToUnicodeEx’s no-state-change flag
within Labrador’s Windows 10 version 1607 floor. Dead,
ambiguous or failed character translations are unavailable; named controls can have localized
names. This is best effort rather than a promise of every keycap or IME legend: a pending dead
key can affect the returned translation, and IME profile changes do not all notify through
WM_INPUTLANGCHANGE.
No layout is loaded, activated or remapped.
In a browser, the shell caches last-observed unmodified key labels from the focused canvas.
An observation must be a single Unicode scalar. ASCII space, C0/C1 controls, line separators,
named and dead keys, Shift/Ctrl/Alt/Meta/CapsLock and composition produce no new label. The shell
requests neither getLayoutMap nor Keyboard Lock. Canvas blur and page hiding discard observations. A changed label for an already observed position discards
older observations before retaining the new fact; an optional layoutchange notification is
used only where the browser actually supplies it. Current Chromium does not expose that event,
so a layout change can remain undetected until focus changes or a differing fact is observed.
The cache is not a complete current-layout snapshot. These limitations change display text,
never the physical mapping, ISO extra-key identity, serialized tokens or binding policy.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.