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_handlers(&self) -> Var<bool>

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

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

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

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 each_update( &self, direct_scope_only: bool, ignore_propagation: bool, handler: impl FnMut(&CommandArgs), )

Visit each new update, oldest first, that target the context widget.

This is similar to Event::each_update, but with extra filtering. If direct_scope_only is enabled only handle exact command scope matches, otherwise the app scope matches all events, the window scope matches all events for the window or widgets in the window and the widget scope matches the widget and all descendants.

pub fn latest_update<O>( &self, direct_scope_only: bool, ignore_propagation: bool, handler: impl FnOnce(&CommandArgs) -> O, ) -> Option<O>

Visit the latest update that targets the context widget.

This is similar to Event::latest_update, but with extra filtering.

pub fn has_update( &self, direct_scope_only: bool, ignore_propagation: bool, ) -> bool

Visit the latest update that targets the context widget.

This is similar to Event::has_update, but with extra filtering.

pub fn on_pre_event( &self, init_enabled: bool, direct_scope_only: bool, ignore_propagation: bool, handler: Handler<CommandArgs>, ) -> CommandHandle

Creates a preview event handler for the command.

This is similar to Event::on_pre_event, but with extra filtering. The handler is only called if handle is enabled and if the scope matches. if direct_scope_only is enabled only handles exact matches, otherwise the app scope matches all events, the window scope matches all events for the window or widgets in the window and the widget scope matches the widget and all descendants.

The init_enabled value defines the handle initial state.

pub fn on_event( &self, init_enabled: bool, direct_scope_only: bool, ignore_propagation: bool, handler: Handler<CommandArgs>, ) -> CommandHandle

Creates an event handler for the command.

This is similar to Event::on_event, but with extra filtering. The handler is only called if the command handle is enabled and if the scope matches. if direct_scope_only is enabled only handles exact matches, otherwise the app scope matches all events, the window scope matches all events for the window or widgets in the window and the widget scope matches the widget and all descendants.

The init_enabled value defines the handle initial state.

pub fn on_pre_event_with_enabled( &self, init_enabled: bool, direct_scope_only: bool, ignore_propagation: bool, handler: Handler<(CommandArgs, Var<bool>)>, ) -> CommandHandle

Sets a handler like Command::on_pre_event, but the args include the handle enabled and the handler is called when the handle is disabled as well.

pub fn on_event_with_enabled( &self, init_enabled: bool, direct_scope_only: bool, ignore_propagation: bool, handler: Handler<(CommandArgs, Var<bool>)>, ) -> CommandHandle

Sets a handler like Command::on_event, but the args include the handle enabled and the handler is called when the handle is disabled as well.

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

Name of the static item that defines this command.

Methods from Deref<Target = Event<CommandArgs>>

pub fn var(&self) -> Var<EventUpdates<A>>

Variable that tracks all the args notified in the last update cycle.

Note that the event variable is only cleared when new notifications are requested.

pub fn var_latest(&self) -> Var<Option<A>>

Variable that tracks the latest update.

Is only None if this event has never notified yet.

pub fn var_map<O: VarValue>( &self, filter_map: impl FnMut(&A) -> Option<O> + Send + 'static, fallback_init: impl Fn() -> O + Send + 'static, ) -> Var<O>

Filter map the latest args.

The variable tracks the latest args that passes the filter_map. Every event update calls the closure for each pending args, latest first, and stops on the first args that produces a new value.

pub fn var_bind<O: VarValue>( &self, other: &Var<O>, filter_map: impl FnMut(&A) -> Option<O> + Send + 'static, ) -> VarHandle

Bind filter the latest args to the variable.

The other variable will be updated with the latest args that passes the filter_map. Every event update calls the closure for each pending args, latest first, and stops on the first args that produces a new value.

pub fn notify(&self, args: A)

Modify the event variable to include the args in the next update.

pub fn each_update(&self, ignore_propagation: bool, handler: impl FnMut(&A))

Visit each new update, oldest first, that target the context widget.

If not called inside an widget visits all updates.

If ignore_propagation is false only calls the handler if the propagation is not stopped.

pub fn find_update<O>( &self, ignore_propagation: bool, handler: impl FnMut(&A) -> Option<O>, ) -> Option<O>

Visit each_update, returns on the first args that produces an O.

pub fn any_update( &self, ignore_propagation: bool, handler: impl FnMut(&A) -> bool, ) -> bool

Visit each_update, returns on the first args that produces true.

pub fn latest_update<O>( &self, ignore_propagation: bool, handler: impl FnOnce(&A) -> O, ) -> Option<O>

Visit the latest update that targets the context widget.

If not called inside an widget visits the latest in general.

If ignore_propagation is false only calls the handler if the propagation is not stopped.

pub fn has_update(&self, ignore_propagation: bool) -> bool

If has at least one update for the context widget.

If ignore_propagation is false only returns true if any propagation is not stopped.

pub fn subscribe(&self, op: UpdateOp, widget_id: WidgetId) -> VarHandle

Subscribe the widget to receive updates when events are relevant to it.

pub fn subscribe_when( &self, op: UpdateOp, widget_id: WidgetId, predicate: impl Fn(&A) -> bool + Send + Sync + 'static, ) -> VarHandle

Subscribe the widget to receive updates when events are relevant to it and the latest args passes the predicate.

pub fn on_pre_event( &self, ignore_propagation: bool, handler: Handler<A>, ) -> VarHandle

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.

If ignore_propagation is set also call handlers for args with stopped propagation.

Returns a VarHandle that can be dropped to unsubscribe, you can also unsubscribe from inside the handler by calling unsubscribe.

Examples

let handle = FOCUS_CHANGED_EVENT.on_pre_event(
    false,
    hn!(|args| {
        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 Handler<A>, there are multiple flavors of handlers, including async handlers that allow calling .await. The handler closures can be declared using hn!, async_hn!, hn_once! and async_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, ignore_propagation: bool, handler: Handler<A>, ) -> VarHandle

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.

If ignore_propagation is set also call handlers for args with stopped propagation.

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

Examples

let handle = FOCUS_CHANGED_EVENT.on_event(
    false,
    hn!(|args| {
        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 Handler<A>, there are multiple flavors of handlers, including async handlers that allow calling .await. The handler closures can be declared using hn!, async_hn!, hn_once! and async_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) -> Receiver<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 as_any(&self) -> &AnyEvent

Deref as AnyEvent.

pub fn hook( &self, handler: impl FnMut(&A) -> bool + Send + 'static, ) -> VarHandle

Setups a callback for just after the event notifications are listed, the closure runs in the root app context, just like var modify and hook closures.

The closure must return true to be retained and false to be dropped.

Any event notification or var modification done in the handler will apply on the same update that notifies this event.

pub async fn wait_match( &self, predicate: impl Fn(&A) -> bool + Send + Sync + 'static, )

Wait until any args, current or new passes the predicate.

pub fn with<R>(&self, visitor: impl FnOnce(&EventUpdates<A>) -> R) -> R

Visit the args current value of var.

Methods from Deref<Target = AnyEvent>

pub fn subscribe(&self, op: UpdateOp, widget_id: WidgetId) -> VarHandle

Subscribe the widget to receive updates when events are relevant to it.

pub fn var(&self) -> AnyVar

Variable that tracks all the args notified in the last update cycle.

Note that the event variable is only cleared when new notifications are requested.

pub fn hook( &self, handler: impl FnMut(&dyn AnyEventArgs) -> bool + Send + 'static, ) -> VarHandle

Setups a callback for just after the event notifications are listed, the closure runs in the root app context, just like var modify and hook closures.

The closure must return true to be retained and false to be dropped.

Any event notification or var modification done in the handler will apply on the same update that notifies this event.

Trait Implementations

impl Clone for Command

fn clone(&self) -> Command

Returns a duplicate 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) -> Var<Txt>

where Self: CommandShortcutExt,

Gets a read-only variable that formats the name and first shortcut formatted as "name (first_shortcut)"

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) -> Var<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