Skip to content

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.

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.

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:

samples/components/gallery_bindings.cpp
BindingResult GalleryBindings::try_bind(GalleryAction action, labrador::Key key)
{
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;

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.

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.

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.

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.

samples/components/binding_label.cpp
BindingKeyLabel binding_key_label(std::optional<std::string_view> label,
std::string_view stable_token, const labrador::RenderResources& resources,
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.");
}
std::wstring fallback = labrador::widen(stable_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);
if (labrador::narrow(wide) != *label || !single_line_label(wide) ||
!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 };

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.

All documentation versions