Struct Event

pub struct Event<A: EventArgs> { /* private fields */ }

Represents an event.

Use the event! macro to declare events.

Implementations

impl<A: EventArgs> Event<A>

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<A: EventArgs> Clone for Event<A>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A: EventArgs> Debug for Event<A>

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

Formats the value using the given formatter.

impl<A: EventArgs> PartialEq<AnyEvent> for Event<A>

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

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

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<A: EventArgs> Copy for Event<A>

impl<A: EventArgs> Eq for Event<A>