Struct Event 

pub struct Event<A>(/* private fields */)
where
    A: EventArgs;

Represents an event variable.

Implementations

impl<A> Event<A>

where A: EventArgs,

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>( &self, filter_map: impl FnMut(&A) -> Option<O> + Send + 'static, fallback_init: impl Fn() -> O + Send + 'static, ) -> Var<O>

where O: VarValue,

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>( &self, other: &Var<O>, filter_map: impl FnMut(&A) -> Option<O> + Send + 'static, ) -> VarHandle

where O: VarValue,

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: Box<dyn FnMut(&A) -> HandlerResult + Send>, ) -> 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: Box<dyn FnMut(&A) -> HandlerResult + Send>, ) -> 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 + 'static)) -> 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<A> Clone for Event<A>

where A: EventArgs,

fn clone(&self) -> Event<A>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<A> Debug for Event<A>

where A: EventArgs,

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

Formats the value using the given formatter.

impl<A> Deref for Event<A>

where A: EventArgs,

type Target = AnyEvent

The resulting type after dereferencing.

fn deref(&self) -> &<Event<A> as Deref>::Target

Dereferences the value.

impl<A> Hash for Event<A>

where A: EventArgs,

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

where H: Hasher,

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<A> PartialEq for Event<A>

where A: EventArgs,

fn eq(&self, other: &Event<A>) -> 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<A> Copy for Event<A>

where A: EventArgs,

impl<A> Eq for Event<A>

where A: EventArgs,