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
impl Command
sourcepub fn subscribe(&self, enabled: bool) -> CommandHandle
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.
sourcepub fn subscribe_wgt(&self, enabled: bool, target: WidgetId) -> CommandHandle
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.
sourcepub fn event(&self) -> Event<CommandArgs>
pub fn event(&self) -> Event<CommandArgs>
Underlying event that represents this command in any scope.
sourcepub fn scope(&self) -> CommandScope
pub fn scope(&self) -> CommandScope
Command scope.
sourcepub fn scoped(self, scope: impl Into<CommandScope>) -> Command
pub fn scoped(self, scope: impl Into<CommandScope>) -> Command
Gets the command in a new scope
.
sourcepub fn with_meta<R>(&self, visit: impl FnOnce(&mut CommandMeta<'_>) -> R) -> R
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
.
sourcepub fn has(&self, update: &EventUpdate) -> bool
pub fn has(&self, update: &EventUpdate) -> bool
Returns true
if the update is for this command and scope.
sourcepub fn on<'a>(&self, update: &'a EventUpdate) -> Option<&'a CommandArgs>
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.
sourcepub fn on_unhandled<'a>(
&self,
update: &'a EventUpdate,
) -> Option<&'a CommandArgs>
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.
sourcepub fn handle<R>(
&self,
update: &EventUpdate,
handler: impl FnOnce(&CommandArgs) -> R,
) -> Option<R>
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.
sourcepub fn has_handlers(&self) -> ReadOnlyArcVar<bool>
pub fn has_handlers(&self) -> ReadOnlyArcVar<bool>
Gets a variable that tracks if this command has any handlers.
sourcepub fn is_enabled(&self) -> ReadOnlyArcVar<bool>
pub fn is_enabled(&self) -> ReadOnlyArcVar<bool>
Gets a variable that tracks if this command has any enabled handlers.
sourcepub fn has_handlers_value(&self) -> bool
pub fn has_handlers_value(&self) -> bool
Gets if the command has handlers without creating a tracking variable for the state.
sourcepub fn is_enabled_value(&self) -> bool
pub fn is_enabled_value(&self) -> bool
Gets if the command is enabled without creating a tracking variable for the state.
sourcepub fn visit_scopes(&self, visitor: impl FnMut(Command))
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.
sourcepub fn notify_descendants(&self, parent: &WidgetInfo)
pub fn notify_descendants(&self, parent: &WidgetInfo)
Schedule a command update without param for all scopes inside parent
.
sourcepub fn notify_param(&self, param: impl Any + Send + Sync)
pub fn notify_param(&self, param: impl Any + Send + Sync)
Schedule a command update with custom param
.
sourcepub fn notify_linked(
&self,
propagation: EventPropagationHandle,
param: Option<CommandParam>,
)
pub fn notify_linked( &self, propagation: EventPropagationHandle, param: Option<CommandParam>, )
Schedule a command update linked with an external event propagation
.
sourcepub fn on_pre_event<H>(&self, enabled: bool, handler: H) -> EventHandlewhere
H: AppHandler<AppCommandArgs>,
pub fn on_pre_event<H>(&self, enabled: bool, handler: H) -> EventHandlewhere
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.
sourcepub fn on_event<H>(&self, enabled: bool, handler: H) -> EventHandlewhere
H: AppHandler<AppCommandArgs>,
pub fn on_event<H>(&self, enabled: bool, handler: H) -> EventHandlewhere
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>>§
sourcepub fn subscribe(&self, widget_id: WidgetId) -> EventHandle
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.
sourcepub fn is_subscriber(&self, widget_id: WidgetId) -> bool
pub fn is_subscriber(&self, widget_id: WidgetId) -> bool
Returns true
if the widget is subscribed to this event.
sourcepub fn has_subscribers(&self) -> bool
pub fn has_subscribers(&self) -> bool
Returns true
if at least one widget is subscribed to this event.
sourcepub fn visit_subscribers(&self, visit: impl FnMut(WidgetId))
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.
sourcepub fn has(&self, update: &EventUpdate) -> bool
pub fn has(&self, update: &EventUpdate) -> bool
Returns true
if the update is for this event.
sourcepub fn on<'a>(&self, update: &'a EventUpdate) -> Option<&'a A>
pub fn on<'a>(&self, update: &'a EventUpdate) -> Option<&'a A>
Get the event update args if the update is for this event.
sourcepub fn on_unhandled<'a>(&self, update: &'a EventUpdate) -> Option<&'a A>
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.
sourcepub fn handle<R>(
&self,
update: &EventUpdate,
handler: impl FnOnce(&A) -> R,
) -> Option<R>
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.
sourcepub fn new_update(&self, args: A) -> EventUpdate
pub fn new_update(&self, args: A) -> EventUpdate
Create an event update for this event with delivery list filtered by the event subscribers.
sourcepub fn new_update_custom(
&self,
args: A,
delivery_list: UpdateDeliveryList,
) -> EventUpdate
pub fn new_update_custom( &self, args: A, delivery_list: UpdateDeliveryList, ) -> EventUpdate
Create and event update for this event with a custom delivery list.
sourcepub fn on_pre_event<H>(&self, handler: H) -> EventHandlewhere
H: AppHandler<A>,
pub fn on_pre_event<H>(&self, handler: H) -> EventHandlewhere
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
.
sourcepub fn on_event(&self, handler: impl AppHandler<A>) -> EventHandle
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
.
sourcepub fn receiver(&self) -> EventReceiver<A>where
A: Send,
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.
sourcepub fn sender(&self) -> EventSender<A>where
A: Send,
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.
sourcepub fn has_hooks(&self) -> bool
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 CommandInfoExt for Command
impl CommandInfoExt for Command
source§impl CommandNameExt for Command
impl CommandNameExt for Command
source§fn name(self) -> CommandMetaVar<Txt>
fn name(self) -> CommandMetaVar<Txt>
source§fn name_with_shortcut(self) -> BoxedVar<Txt>where
Self: CommandShortcutExt,
fn name_with_shortcut(self) -> BoxedVar<Txt>where
Self: CommandShortcutExt,
name
source§impl CommandShortcutExt for Command
impl CommandShortcutExt for Command
source§fn shortcut(self) -> CommandMetaVar<Shortcuts>
fn shortcut(self) -> CommandMetaVar<Shortcuts>
source§fn shortcut_filter(self) -> CommandMetaVar<ShortcutFilter>
fn shortcut_filter(self) -> CommandMetaVar<ShortcutFilter>
shortcut
is valid.source§fn init_shortcut(self, shortcut: impl Into<Shortcuts>) -> Self
fn init_shortcut(self, shortcut: impl Into<Shortcuts>) -> Self
source§fn init_shortcut_filter(self, filter: impl Into<ShortcutFilter>) -> Self
fn init_shortcut_filter(self, filter: impl Into<ShortcutFilter>) -> Self
impl Copy for Command
impl Eq for Command
Auto Trait Implementations§
impl Freeze for Command
impl RefUnwindSafe for Command
impl Send for Command
impl Sync for Command
impl Unpin for Command
impl UnwindSafe for Command
Blanket Implementations§
source§impl<T> AnyVarValue for Twhere
T: VarValue,
impl<T> AnyVarValue for Twhere
T: VarValue,
source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
dyn Any
methods.source§fn clone_boxed(&self) -> Box<dyn AnyVarValue>
fn clone_boxed(&self) -> Box<dyn AnyVarValue>
source§fn clone_boxed_var(&self) -> Box<dyn AnyVar>
fn clone_boxed_var(&self) -> Box<dyn AnyVar>
LocalVar<Self>
.source§fn eq_any(&self, other: &(dyn AnyVarValue + 'static)) -> bool
fn eq_any(&self, other: &(dyn AnyVarValue + 'static)) -> bool
self
equals other
.source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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