Macro command_property

macro_rules! command_property {
    ($(
        $(#[$on_cmd_attrs:meta])*
        $vis:vis fn $command:ident {
            cmd: $cmd_init:expr
            $(, enabled: $enabled_var:expr)?
            $(, widget_impl: $Wgt:ty)?
            $(,)?
        }
    )+) => { ... };
}

Declare one or more command event properties.

Each declaration expands to two properties on_$command and on_pre_$command. The preview properties call on_pre_command, the main event properties call on_command.

Examples

command_property! {
    /// Paste command property docs.
    pub fn paste {
        cmd: PASTE_CMD.scoped(WIDGET.id()),
        // enabled: LocalVar(true), // default enabled
    }
}

Command

The cmd: expression evaluates on init to generate the command, this allows for the creation of widget scoped commands. The new command property event handler will receive events for the command and scope that target the widget where the property is set.

If the command is scoped on the root widget and the command property is set on the same root widget a second handle is taken for the window scope too, so callers can target the window using the window ID or the root widget ID.

Enabled

The enabled: expression evaluates on init to generate a boolean variable that defines if the command handle is enabled. Command event handlers track both their existence and the enabled flag, see Command::subscribe for details.

If not provided the command is always enabled.

Async

Async event handlers are supported by properties generated by this macro, but only the code before the first .await executes in the event track, subsequent code runs in widget updates.

Implement For

You can implement the new properties for a widget or mix-in using the widget_impl: directive:

/// Clipboard handler.
#[widget_mixin]
pub struct ClipboardMix<P>(P);

command_property! {
    /// Paste command property docs.
    pub fn paste {
        cmd: PASTE_CMD.scoped(WIDGET.id()),
        widget_impl: ClipboardMix<P>,
    }
}