Struct Command

pub struct Command { /* private fields */ }

Identifies a command event.

Use the command! to declare commands, it declares command static items with optional metadata initialization.

command! {
    /// Foo-bar command.
    pub static FOO_BAR_CMD = {
        foo: true,
        bar: false,
    };
}

Metadata

Commands can have associated metadata, this metadata is extendable and can be used to enable command features such as command shortcuts. The metadata can be accessed using with_meta, metadata extensions traits can use this metadata to store state. See CommandMeta for more details.

Handles

Unlike other events, commands only notify if it has at least one handler, handlers must call subscribe to indicate that the command is relevant to the current app state and set the subscription handle enabled flag to indicate that the handler can fulfill command requests.

Scopes

Commands are global by default, meaning an enabled handle anywhere in the app enables it everywhere. You can use scoped to declare sub-commands that are the same command event, but filtered to a scope, metadata of scoped commands inherit from the app scope metadata, but can be overridden just for the scope.

Implementations

impl Command

pub fn subscribe(&self, enabled: bool) -> CommandHandle

Create a new handle to this command.

A handle indicates that command handlers are present in the current app, the enabled flag indicates the handler is ready to fulfill command requests.

If the command is scoped on a window or widget if it is added to the command event subscribers.

pub fn subscribe_wgt(&self, enabled: bool, target: WidgetId) -> CommandHandle

Create a new handle for this command for a handler in the target widget.

The handle behaves like subscribe, but include the target on the delivery list for app scoped commands. Note this only works for global commands (app scope), window and widget scoped commands only notify the scope so the target is ignored for scoped commands.

pub fn event(&self) -> Event<CommandArgs>

Underlying event that represents this command in any scope.

pub fn scope(&self) -> CommandScope

Command scope.

pub fn scoped(self, scope: impl Into<CommandScope>) -> Command

Gets the command in a new scope.

pub fn with_meta<R>(&self, visit: impl FnOnce(&mut CommandMeta<'_>) -> R) -> R

Visit the command custom metadata of the current scope.

Metadata for CommandScope::App is retained for the duration of the app, metadata scoped on window or widgets is dropped after an update cycle with no handler and no strong references to has_handlers and is_enabled.

pub fn has(&self, update: &EventUpdate) -> bool

Returns true if the update is for this command and scope.

pub fn on<'a>(&self, update: &'a EventUpdate) -> Option<&'a CommandArgs>

Get the command update args if the update is for this command and scope.

pub fn on_unhandled<'a>( &self, update: &'a EventUpdate, ) -> Option<&'a CommandArgs>

Get the event update args if the update is for this event and propagation is not stopped.

pub fn handle<R>( &self, update: &EventUpdate, handler: impl FnOnce(&CommandArgs) -> R, ) -> Option<R>

Calls handler if the update is for this event and propagation is not stopped, after the handler is called propagation is stopped.

pub fn has_handlers(&self) -> ReadOnlyArcVar<bool>

Gets a variable that tracks if this command has any handlers.

pub fn is_enabled(&self) -> ReadOnlyArcVar<bool>

Gets a variable that tracks if this command has any enabled handlers.

pub fn has_handlers_value(&self) -> bool

Gets if the command has handlers without creating a tracking variable for the state.

pub fn is_enabled_value(&self) -> bool

Gets if the command is enabled without creating a tracking variable for the state.

pub fn visit_scopes<T>( &self, visitor: impl FnMut(Command) -> ControlFlow<T>, ) -> Option<T>

Calls visitor for each scope of this command.

Note that scoped commands are removed if unused, see with_meta for more details.

pub fn notify(&self)

Schedule a command update without param.

pub fn notify_descendants(&self, parent: &WidgetInfo)

Schedule a command update without param for all scopes inside parent.

pub fn notify_param(&self, param: impl Any + Send + Sync)

Schedule a command update with custom param.

pub fn notify_linked( &self, propagation: EventPropagationHandle, param: Option<CommandParam>, )

Schedule a command update linked with an external event propagation.

pub fn on_pre_event<H>(&self, enabled: bool, handler: H) -> EventHandle

where H: AppHandler<AppCommandArgs>,

Creates a preview event handler for the command.

This is similar to Event::on_pre_event, but handler is only called if the command scope matches.

The enabled parameter defines the initial state of the command subscription, the subscription handle is available in the handler args.

pub fn on_event<H>(&self, enabled: bool, handler: H) -> EventHandle

where H: AppHandler<AppCommandArgs>,

Creates an event handler for the command.

This is similar to Event::on_event, but handler is only called if the command scope matches.

The enabled parameter defines the initial state of the command subscription, the subscription handle is available in the handler args.

Methods from Deref<Target = Event<CommandArgs>>

pub fn as_any(&self) -> AnyEvent

Gets the event without the args type.

pub fn subscribe(&self, widget_id: WidgetId) -> EventHandle

Register the widget to receive targeted events from this event.

Widgets only receive events if they are in the delivery list generated by the event args and are subscribers to the event. App extensions receive all events.

pub fn is_subscriber(&self, widget_id: WidgetId) -> bool

Returns true if the widget is subscribed to this event.

pub fn has_subscribers(&self) -> bool

Returns true if at least one widget is subscribed to this event.

pub fn visit_subscribers<T>( &self, visit: impl FnMut(WidgetId) -> ControlFlow<T>, ) -> Option<T>

Calls visit for each widget subscribed to this event.

Note that trying to subscribe or add hook inside visit will deadlock. Inside visit you can notify the event and generate event updates.

pub fn name(&self) -> &'static str

Name of the event static item.

pub fn has(&self, update: &EventUpdate) -> bool

Returns true if the update is for this event.

pub fn on<'a>(&self, update: &'a EventUpdate) -> Option<&'a A>

Get the event update args if the update is for this event.

pub fn on_unhandled<'a>(&self, update: &'a EventUpdate) -> Option<&'a A>

Get the event update args if the update is for this event and propagation is not stopped.

pub fn handle<R>( &self, update: &EventUpdate, handler: impl FnOnce(&A) -> R, ) -> Option<R>

Calls handler if the update is for this event and propagation is not stopped, after the handler is called propagation is stopped.

pub fn new_update(&self, args: A) -> EventUpdate

Create an event update for this event with delivery list filtered by the event subscribers.

pub fn new_update_custom( &self, args: A, delivery_list: UpdateDeliveryList, ) -> EventUpdate

Create and event update for this event with a custom delivery list.

pub fn notify(&self, args: A)

Schedule an event update.

pub fn on_pre_event<H>(&self, handler: H) -> EventHandle

where H: AppHandler<A>,

Creates a preview event handler.

The event handler is called for every update that has not stopped propagation. The handler is called before widget handlers and on_event handlers. The handler is called after all previous registered preview handlers.

Returns an EventHandle that can be dropped to unsubscribe, you can also unsubscribe from inside the handler by calling unsubscribe in the third parameter of app_hn! or async_app_hn!.

Examples

let handle = FOCUS_CHANGED_EVENT.on_pre_event(app_hn!(|args: &FocusChangedArgs, _| {
    println!("focused: {:?}", args.new_focus);
}));

The example listens to all FOCUS_CHANGED_EVENT events, independent of widget context and before all UI handlers.

Handlers

the event handler can be any type that implements AppHandler, there are multiple flavors of handlers, including async handlers that allow calling .await. The handler closures can be declared using app_hn!, async_app_hn!, app_hn_once! and async_app_hn_once!.

Async

Note that for async handlers only the code before the first .await is called in the preview moment, code after runs in subsequent event updates, after the event has already propagated, so stopping propagation only causes the desired effect before the first .await.

pub fn on_event(&self, handler: impl AppHandler<A>) -> EventHandle

Creates an event handler.

The event handler is called for every update that has not stopped propagation. The handler is called after all on_pre_event all widget handlers and all on_event handlers registered before this one.

Returns an EventHandle that can be dropped to unsubscribe, you can also unsubscribe from inside the handler by calling unsubscribe in the third parameter of app_hn! or async_app_hn!.

Examples

let handle = FOCUS_CHANGED_EVENT.on_event(app_hn!(|args: &FocusChangedArgs, _| {
    println!("focused: {:?}", args.new_focus);
}));

The example listens to all FOCUS_CHANGED_EVENT events, independent of widget context, after the UI was notified.

Handlers

the event handler can be any type that implements AppHandler, there are multiple flavors of handlers, including async handlers that allow calling .await. The handler closures can be declared using app_hn!, async_app_hn!, app_hn_once! and async_app_hn_once!.

Async

Note that for async handlers only the code before the first .await is called in the preview moment, code after runs in subsequent event updates, after the event has already propagated, so stopping propagation only causes the desired effect before the first .await.

pub fn receiver(&self) -> EventReceiver<A>

where A: Send,

Creates a receiver channel for the event. The event updates are send on hook, before even preview handlers. The receiver is unbounded, it will fill indefinitely if not drained. The receiver can be used in any thread, including non-app threads.

Drop the receiver to stop listening.

pub fn sender(&self) -> EventSender<A>

where A: Send,

Creates a sender channel that can notify the event.

Events can notify from any app thread, this sender can notify other threads too.

pub fn has_hooks(&self) -> bool

Returns true if any app level callback is registered for this event.

This includes AnyEvent::hook, Event::on_pre_event, Event::on_event and Event::receiver.

Trait Implementations

impl Clone for Command

fn clone(&self) -> Command

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CommandInfoExt for Command

fn info(self) -> CommandMetaVar<Txt>

Gets a read-write variable that is a short informational string about the command.

fn init_info(self, info: impl Into<Txt>) -> Self

Sets the initial info if it is not set.

impl CommandNameExt for Command

fn name(self) -> CommandMetaVar<Txt>

Gets a read-write variable that is the display name for the command.

fn init_name(self, name: impl Into<Txt>) -> Self

Sets the initial name if it is not set.

fn name_with_shortcut(self) -> BoxedVar<Txt>

where Self: CommandShortcutExt,

Gets a read-only variable that formats the name and first shortcut in the following format: name (first_shortcut) Note: If no shortcuts are available this method returns the same as name

impl CommandShortcutExt for Command

fn shortcut(self) -> CommandMetaVar<Shortcuts>

Gets a read-write variable that is zero-or-more shortcuts that invoke the command.

fn shortcut_filter(self) -> CommandMetaVar<ShortcutFilter>

Gets a read-write variable that sets a filter for when the shortcut is valid.

fn init_shortcut(self, shortcut: impl Into<Shortcuts>) -> Self

Sets the initial shortcuts.

fn init_shortcut_filter(self, filter: impl Into<ShortcutFilter>) -> Self

Sets the initial shortcut filters.

fn shortcut_txt(self) -> BoxedVar<Txt>

where Self: Sized,

Gets a read-only variable that is the display text for the first shortcut.

impl Debug for Command

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Command

type Target = Event<CommandArgs>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for Command

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Command

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Command

impl Eq for Command