Struct zng_app::event::Command

source ·
pub struct Command { /* private fields */ }
Expand description

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§

source§

impl Command

source

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.

source

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.

source

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

Underlying event that represents this command in any scope.

source

pub fn scope(&self) -> CommandScope

Command scope.

source

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

Gets the command in a new scope.

source

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.

source

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

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

source

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.

source

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.

source

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.

source

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

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

source

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

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

source

pub fn has_handlers_value(&self) -> bool

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

source

pub fn is_enabled_value(&self) -> bool

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

source

pub fn visit_scopes(&self, visitor: impl FnMut(Command))

Calls visitor for each scope of this command.

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

source

pub fn notify(&self)

Schedule a command update without param.

source

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

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

source

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

Schedule a command update with custom param.

source

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

Schedule a command update linked with an external event propagation.

source

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

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.

source

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

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>>§

source

pub fn as_any(&self) -> AnyEvent

Gets the event without the args type.

source

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.

source

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

Returns true if the widget is subscribed to this event.

source

pub fn has_subscribers(&self) -> bool

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

source

pub fn visit_subscribers(&self, visit: impl FnMut(WidgetId))

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.

source

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

Name of the event static item.

source

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

Returns true if the update is for this event.

source

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

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

source

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.

source

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.

source

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

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

source

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

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

source

pub fn notify(&self, args: A)

Schedule an event update.

source

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.

source

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.

source

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.

source

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.

source

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§

source§

impl Clone for Command

source§

fn clone(&self) -> Command

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl CommandInfoExt for Command

source§

fn info(self) -> CommandMetaVar<Txt>

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

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

Sets the initial info if it is not set.
source§

impl CommandNameExt for Command

source§

fn name(self) -> CommandMetaVar<Txt>

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

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

Sets the initial name if it is not set.
source§

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
source§

impl CommandShortcutExt for Command

source§

fn shortcut(self) -> CommandMetaVar<Shortcuts>

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

fn shortcut_filter(self) -> CommandMetaVar<ShortcutFilter>

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

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

Sets the initial shortcuts.
source§

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

Sets the initial shortcut filters.
source§

fn shortcut_txt(self) -> BoxedVar<Txt>
where Self: Sized,

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

impl Debug for Command

source§

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

Formats the value using the given formatter. Read more
source§

impl Deref for Command

source§

type Target = Event<CommandArgs>

The resulting type after dereferencing.
source§

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

Dereferences the value.
source§

impl Hash for Command

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

impl PartialEq for Command

source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

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

impl Copy for Command

source§

impl Eq for Command

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> AnyVarValue for T
where T: VarValue,

source§

fn as_any(&self) -> &(dyn Any + 'static)

Access to dyn Any methods.
source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Access to mut dyn Any methods.
source§

fn clone_boxed(&self) -> Box<dyn AnyVarValue>

Clone the value.
source§

fn clone_boxed_var(&self) -> Box<dyn AnyVar>

Clone the value into a new boxed LocalVar<Self>.
source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Access to Box<dyn Any> methods.
source§

fn eq_any(&self, other: &(dyn AnyVarValue + 'static)) -> bool

Gets if self equals other.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> IntoVar<T> for T
where T: VarValue,

source§

type Var = LocalVar<T>

Variable type that will wrap the T value. Read more
source§

fn into_var(self) -> <T as IntoVar<T>>::Var

Converts the source value into a var.
source§

fn into_boxed_var(self) -> Box<dyn VarBoxed<T>>
where Self: Sized,

Converts into BoxedVar<T>. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
source§

impl<T> IntoValue<T> for T
where T: VarValue,

source§

impl<T> StateValue for T
where T: Any + Send + Sync,

source§

impl<T> VarValue for T
where T: Debug + Clone + PartialEq + Any + Send + Sync,