Skip to content

Shortcuts

Header: winui/ui/containers/Shortcuts.hpp. Spec: winui/ui/containers/Shortcuts.hpp.

ui::Shortcuts

Keyboard shortcuts for one area of a window. Builds a ui::ContentHost around .content.

Each shortcut fires while keyboard focus is anywhere inside .content, and only then. The focused control gets the key first, then the shortcuts of the innermost area, then those of the areas around it. For a shortcut that fires wherever focus is, give a ui::Command its .shortcut and register it with Window::add_command(), or offer it through a button or menu item.

Example: 

ui::Property<std::string> message;
window.set_content(ui::Shortcuts{
    .items =
        {
            ui::Shortcut{.keys = ui::Ctrl + ui::Key::Enter, .on_pressed = [&] { std::print("{}", message.get()); }},
            ui::Shortcut{.keys = ui::Key::Escape, .on_pressed = [&] { message = ""; }},
        },
    .content = ui::TextBox{.header = "Message", .text = message, .accepts_return = true},
});

Every field, in the order a designated initializer names them:

ui::Shortcuts{
    .items, .style, .margin, .width, .height, .min_width, .min_height, .max_width, .max_height,
    .horizontal_alignment, .vertical_alignment, .visible, .tool_tip, .accessibility,
    .on_pointer_entered, .on_pointer_exited, .on_got_focus, .on_lost_focus, .on_key_down,
    .on_wheel, .control, .content
}

Fields, in declaration order (designators must follow it):

Field Type Default
items ui::ShortcutList The shortcuts. One that returns ui::NotHandled lets the key go on to the shortcuts further out.
on_pointer_entered ui::Action The pointer moved onto the control.
on_pointer_exited ui::Action The pointer left the control.
on_got_focus ui::Action Keyboard focus arrived on the control, or on anything inside it, from outside it. A control with nothing focusable in it never gets focus, and never raises this.
on_lost_focus ui::Action Keyboard focus left the control and everything inside it.
on_key_down ui::Callback<ui::Handling(const ui::KeyEvent&)> A key pressed while focus is on the control or inside it, before the control's own handling; ui::Handled stops it there (Element::on_key_down()).
on_wheel ui::Callback<ui::Handling(const ui::PointerEvent&)> A wheel turn over the control, before the control scrolls; ui::Handled stops it there (Element::on_wheel()).
control ui::ControlOut<ui::Shortcuts> Out: the handle that receives the built control.
content ui::Spec The area the shortcuts belong to.

Plus the common fields style, margin, width, height, min_width, min_height, max_width, max_height, horizontal_alignment, vertical_alignment, visible, tool_tip, accessibility every spec carries (conventions).

build

std::unique_ptr<Element> build()&&

Consumes the spec and returns the built ui::ContentHost; the caller owns it.

struct Shortcut

A key combination that invokes an action while focus is inside the element that holds it (Element::add_shortcut()). Unless on_pressed returns ui::NotHandled the key goes no further; a NotHandled one goes on to an ancestor's shortcuts and then to the focused element.

Example: 

auto* editor = window.set_content(
    std::make_unique<ui::StackControl>(ui::Orientation::Vertical));
editor->add_shortcut({.keys = ui::Ctrl + ui::Key::S, .on_pressed = [] { save_document(); }});
// Ctrl+S now saves whenever focus is anywhere inside `editor`.

Field Type Default
keys KeyCombo The key and exactly the modifiers that fire it; an empty key combination never matches.
on_pressed Callback<Handling()> The action. Returning nothing, or ui::Handled, stops the key; ui::NotHandled lets it go on.

class ShortcutList

The shortcuts of a ui::Shortcuts, written as a braced list of ui::Shortcut. A shortcut owns its handler, which may capture move-only state, so the list takes them by value.

entries

std::vector<Shortcut> entries

The shortcuts, in order.

ShortcutList

ShortcutList() = default

No shortcuts.

ShortcutList

template <typename... S>
ShortcutList(S&& ... items)
    requires (sizeof...(S) > 0 && (std::same_as<S, Shortcut> && ...))

The shortcuts in order. Implicit, so .items = {ui::Shortcut{...}, ...} works.

ShortcutList

ShortcutList(const ShortcutList&) = delete

Move-only, since a shortcut owns its handler.

operator=

ShortcutList& operator=(const ShortcutList&) = delete

ShortcutList

ShortcutList(ShortcutList&&) = default

operator=

ShortcutList& operator=(ShortcutList&&) = default

add

void add(Shortcut shortcut)

Appends one shortcut, for a list put together in a loop.

Tests

  • tests/test_shortcuts.cpp