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