Macro event_property

macro_rules! event_property {
    ($(
        $(#[$on_event_attrs:meta])*
        $vis:vis fn $event:ident {
            event: $EVENT:path,
            args: $Args:path
            $(, filter: $filter:expr)?
            $(, widget_impl: $Wgt:ty)?
            $(, with: $with:expr)?
            $(,)?
        }
    )+) => { ... };
}

Declare one or more event properties.

Each declaration expands to two properties on_$event and on_pre_$event. The preview properties call on_pre_event, the main event properties call on_event.

Examples

event_property! {
    /// on_key_input docs.
    pub fn key_input {
        event: KEY_INPUT_EVENT,
        args: KeyInputArgs,
        // default filter is |args| true,
    }

    pub(crate) fn key_down {
        event: KEY_INPUT_EVENT,
        args: KeyInputArgs,
        // optional filter:
        filter: |args| args.state == KeyState::Pressed,
    }
}

Filter

App events are delivered to all widgets that are both in the UpdateDeliveryList and event subscribers list, event properties can specialize further by defining a filter predicate.

The filter: predicate is called if propagation is not stopped. It must return true if the event arguments are relevant in the context of the widget and event property. If it returns true the handler closure is called. See on_event and on_pre_event for more information.

If you don’t provide a filter predicate the default always allows, so all app events targeting the widget and not already handled are allowed by default. Note that events that represent an interaction with the widget are send for both ENABLED and DISABLED widgets, event properties should probably distinguish if they fire on normal interactions versus on disabled interactions.

Async

Async event handlers are supported by properties generated by this macro, but only the code before the first .await executes in the event track, subsequent code runs in widget updates.

Commands

You can use command_property to declare command event properties.

Implement For

You can implement the new properties for a widget or mix-in using the widget_impl: directive:

/// Keyboard events.
#[widget_mixin]
pub struct KeyboardMix<P>(P);

event_property! {
    pub fn key_input {
        event: KEY_INPUT_EVENT,
        args: KeyInputArgs,
        widget_impl: KeyboardMix<P>,
    }
}

With Extra Nodes

You can wrap the event handler node with extra nodes by setting the optional with: closure:

event_property! {
    pub fn key_input {
        event: KEY_INPUT_EVENT,
        args: KeyInputArgs,
        with: |child, _preview| some_node(child),
    }
}

The closure receives two arguments, the handler UiNode and a bool that is true if the closure is called in the on_pre_ property or false when called in the on_ property.