ui::Command¶

Header: winui/ui/Command.hpp.

An action together with what every control invoking it would otherwise repeat: text, an icon, a shortcut, a description and whether it may run.

Point an AppBarButton, MenuItem or SwipeItem at one, and each fills in whatever of those it has not been given itself. It takes the text and the icon, and shows the description as its tooltip. On an AppBarButton or a MenuItem, the shortcut fires app-wide while the control is in the window, and a menu shows it as "Ctrl+D". A SwipeItem does not register the shortcut. A Button, ToggleButton, DropdownButton or SplitButton runs the command, takes its enabled state and uses its description as the tooltip when it has none, but keeps its own text.

Every field takes a value or a binding, and every control using the command follows a bound field as it changes. With .enabled = has_selection, every button and menu item pointing at the command is enabled and disabled with has_selection. A control's own .enabled still applies, so the control is enabled only while both allow it.

Write the command down once and give it to every control that offers it: .command = save. As with a Property, either the command or the controls may be destroyed first. A control whose command was destroyed acts as if it had none. A plain field is a value fixed at construction, as on a spec, so bind a field that should change.

Example:

ui::Property<std::string> output{};
ui::Property<bool>        has_item{true};
ui::Command favorite{
    .text        = "Add to favorites",
    .icon        = ui::Symbol::Favorite,
    .shortcut    = ui::Ctrl + ui::Key::D,
    .description = "Mark the selected item as a favorite",
    .enabled     = has_item,
    .execute     = [&](std::string_view item) { output = "Favorited " + std::string(item); },
};

window.set_content(ui::VerticalStack{
    .content = {
        ui::Button{.text = "Favorite", .command = favorite, .command_parameter = "Item 1"},
        ui::Text{.text = output},
    },
});
has_item = false; // the button disables itself, and Ctrl+D does nothing

text¶

Binding<std::string> text {}

UTF-8 text, used by an app-bar button, a menu item or a swipe item that has no text of its own.

icon¶

Binding<IconSource> icon {}

The invoking control's icon when it has none; empty by default.

shortcut¶

Binding<KeyCombo> shortcut {}

The shortcut. It fires app-wide while a control offering the command is in the window, and the control shows it as its shortcut text.

description¶

Binding<std::string> description {}

The invoking control's tooltip, unless it has one.

enabled¶

Binding<bool> enabled {true}

Whether the command may run. Every control using it is disabled while this is false, on top of its own .enabled, and operator() does nothing.

execute¶

CommandHandler execute {}

Run by operator() with the invoking control's .command_parameter, while enabled.

live_¶

detail::CommandLive live_ {}

Internal: the current values, kept by the command itself. Never set it.

current¶

const CommandValues& current() const

What the fields hold right now, with each bound field's latest value.

observe¶

Subscription observe(Callback<void()> fn) const

Calls fn after any bound field changes. The returned Subscription must be kept for fn to keep firing; a control using the command keeps one to redraw.

operator()¶

void operator()(std::string_view parameter = {}) const

Runs execute with parameter while the command is enabled; otherwise does nothing.