Macro command

macro_rules! command {
    ($(
        $(#[$attr:meta])*
        $vis:vis static $COMMAND:ident $(=> |$cmd:ident|$custom_meta_init:expr ;)? $(= { $($meta_ident:ident $(!)? : $meta_init:expr),* $(,)? };)? $(;)?
    )+) => { ... };
}

Declares new Command static items.

Command static items represent widget or service actions. Command items are also events, that is they dereference to Event<A> and override some event methods to enable communication from the command subscribers to the command notifier. Command static items also host metadata about the command.

Conventions

Command events have the _CMD suffix, for example a command for the clipboard copy action is called COPY_CMD. Public and user facing commands also set the CommandNameExt and CommandInfoExt with localized display text.

Shortcuts

You can give commands one or more shortcuts using the CommandShortcutExt, the GestureManager notifies commands that match a pressed shortcut automatically.

Properties

If the command implementation is not specific you can use command_property! to declare properties that setup command handlers for the command.

Examples

Declare two commands:

use zng_app::event::command;

command! {
    static FOO_CMD;

    /// Command docs.
    pub(crate) static BAR_CMD;
}

You can also initialize metadata:

use zng_app::{event::{command, CommandNameExt, CommandInfoExt}, shortcut::{CommandShortcutExt, shortcut}};

command! {
    /// Represents the **foo** action.
    pub static FOO_CMD = {
        name: "Foo!",
        info: "Does the foo thing",
        shortcut: shortcut![CTRL+'F'],
    };
}

The initialization uses the command extensions pattern and runs once for each app.

Or you can use a custom closure to initialize the command:

use zng_app::{event::{command, CommandNameExt, CommandInfoExt}, shortcut::{CommandShortcutExt, shortcut}};

command! {
    /// Represents the **foo** action.
    pub static FOO_CMD => |cmd| {
        cmd.init_name("Foo!");
        cmd.init_info("Does the foo thing.");
        cmd.init_shortcut(shortcut![CTRL+'F']);
    };
}

For the first kind of metadata initialization a documentation section is also generated with a table of metadata.

Localization

If the first metadata is l10n!: the command init will attempt to localize the other string metadata. The cargo zng l10n command line tool scraps commands that set this special metadata.

command! {
    pub static FOO_CMD = {
        l10n!: true,
        name: "Foo!",
        info: "Does the foo thing",
    };
}

The example above will be scrapped as:

FOO_CMD =
    .name = Foo!
    .info = Does the foo thing.

The l10n!: meta can also be set to a localization file name:

command! {
    pub static FOO_CMD = {
        l10n!: "file",
        name: "Foo!",
    };
}

The example above is scrapped to {l10n-dir}/{lang}/file.ftl files.

Limitations

Interpolation is not supported in command localization strings.

The l10n!: value must be a textual literal, that is, it can be only a string literal or a bool literal, and it cannot be inside a macro expansion.