Fixed docs.

tests/build/impl_ui_node/delegate_expr_error_incorrect_type.stderr

@@ -41,8 +41,8 @@ error[E0277]: the trait bound `NotANode: UiNode` is not satisfied
    |
   ::: $WORKSPACE/zero-ui-core/src/ui_node.rs
    |
-   |     fn event<EU: EventUpdateArgs>(&mut self, ctx: &mut WidgetContext, args: &EU);
-   |                  --------------- required by this bound in `event`
+   |     fn event<A: EventUpdateArgs>(&mut self, ctx: &mut WidgetContext, args: &A);
+   |                 --------------- required by this bound in `event`
 
 error[E0277]: the trait bound `NotANode: UiNode` is not satisfied
    --> $DIR/delegate_expr_error_incorrect_type.rs:9:27

zero-ui-core/src/event.rs

@@ -70,8 +70,7 @@ mod protected {
 pub struct EventUpdate<E: Event>(E::Args);
 impl<E: Event> EventUpdate<E> {
     /// Clone the arguments.
-    #[inline]
-    #[allow(clippy::should_implement_trait)] // that is what we want
+    #[allow(clippy::should_implement_trait)] // that is what we want.
     pub fn clone(&self) -> E::Args {
         self.0.clone()
     }
@@ -372,7 +371,7 @@ impl Events {
     /// The handler is called before UI handlers and [`on_event`](Self::on_event) handlers, it is called after all previous registered
     /// preview handlers.
     ///
-    /// Drop all clones of the [`EventHandler`] object to unsubscribe.
+    /// Drop the [`EventHandler`] object to unsubscribe.
     ///
     /// # Example
     ///
@@ -412,10 +411,6 @@ impl Events {
     /// The handler is called after all [`on_pre_event`],(Self::on_pre_event) all UI handlers and all [`on_event`](Self::on_event) handlers
     /// registered before this one.
     ///
-    /// Creating a [listener](Events::listen) is slightly more efficient then this and also gives you access to args marked
-    /// with [`stop_propagation`](EventArgs::stop_propagation), this method exists for the convenience of listening on
-    /// an event at the app level without having to declare an [`AppExtension`](crate::app::AppExtension) or a weird property.
-    ///
     /// Drop all clones of the [`EventHandler`] object to unsubscribe.
     ///
     /// # Example
@@ -556,6 +551,12 @@ macro_rules! event_args {
             pub fn stop_propagation_requested(&self) -> bool {
                 <Self as $crate::event::EventArgs>::stop_propagation_requested(self)
             }
+
+            /// If the event described by these arguments is relevant in the given widget context.
+            #[inline]
+            pub fn concerns_widget(&self, ctx: &mut $crate::context::WidgetContext) -> bool {
+                <Self as $crate::event::EventArgs>::concerns_widget(self, ctx)
+            }
         }
         impl $crate::event::EventArgs for $Args {
             #[inline]

zero-ui-core/src/sync.rs

@@ -399,7 +399,7 @@ trait SyncChannel {
     fn update(&self, ctx: &mut AppSyncContext) -> Retain;
 }
 
-/// Represents an [`EventEmitter`] that can be updated from other threads.
+/// Represents an [`Event`] that can be updated from other threads.
 ///
 /// See [`Sync::event_sender`] for more details.
 pub struct EventSender<E>
@@ -469,7 +469,7 @@ where
     }
 }
 
-/// Represents an [`EventListener`] that can receive updates from other threads.
+/// Represents an [`Event`] that can receive updates from other threads.
 ///
 /// See [`Sync::event_receiver`] for more details.
 #[derive(Clone)]

zero-ui-core/src/ui_node.rs

@@ -43,17 +43,56 @@ pub trait UiNode: 'static {
 
     /// Called every time an event updates.
     ///
+    /// Every call to this method is for a single update of a single event type, you can listen to events
+    /// using [`Event::update`]. This method is called even if [`stop_propagation`](crate::event::EventArgs::stop_propagation) 
+    /// was requested, or a parent widget is disabled, and it must always propagate to descendent nodes.
+    ///
+    /// Event propagation can be statically or dynamically typed, the way to listen to both is the same, `A` can be an
+    /// [`AnyEventUpdate`] instance that is resolved dynamically or an [`EventUpdate`](crate::event::EventUpdate) instance
+    /// that is resolved statically in the [`Event::update`] call. If an event matches you should **use the returned args**
+    /// in the call the descendant nodes, **this upgrades from dynamic to static resolution** in descendant nodes increasing
+    /// performance.
+    ///
+    /// If the event is handled before the call in descendant nodes it is called a *preview*, this behavior matches what
+    /// happens in the [`on_pre_event`](crate::event::on_pre_event) node.
+    ///
     /// # Example
     ///
     /// ```
-    /// // TODO demonstrate how to pass call to children.
+    /// # use zero_ui_core::{UiNode, impl_ui_node, context::WidgetContext, widget_base::IsEnabled, event::EventUpdateArgs, gesture::ClickEvent};
+    /// struct MyNode<C> {
+    ///     child: C,
+    ///     click_count: usize
+    /// }
+    /// #[impl_ui_node(child)]
+    /// impl<C: UiNode> UiNode for MyNode<C> {
+    ///     fn event<A: EventUpdateArgs>(&mut self, ctx: &mut WidgetContext, args: &A) { 
+    ///         if let Some(args) = ClickEvent::update(args) {
+    ///             if args.concerns_widget(ctx) && IsEnabled::get(ctx.vars) && !args.stop_propagation_requested() {
+    ///                 self.click_count += 1;
+    ///                 args.stop_propagation();
+    ///                 println!("clicks blocked {}", self.click_count);
+    ///             }
+    ///             self.child.event(ctx, args);
+    ///         }
+    ///         else {
+    ///             self.child.event(ctx, args);
+    ///         }
+    ///     }
+    /// }
     /// ```
-    fn event<EU: EventUpdateArgs>(&mut self, ctx: &mut WidgetContext, args: &EU);
+    ///
+    /// In the example the `ClickEvent` event is handled in *preview* style (before child), but only if 
+    /// the parent widget was clicked and the widget is enabled and stop propagation was not requested. The event
+    /// is then propagated to the `child` node, `self.child.event` appears to be called twice but if the `if` call
+    /// we ensured that the descendant nodes will resolve the event statically, which can not be the case in the `else`
+    /// call where `A` can be the dynamic resolver.
+    fn event<A: EventUpdateArgs>(&mut self, ctx: &mut WidgetContext, args: &A);
 
     /// Called every time an update is requested.
     ///
     /// An update happens every time after a sequence of [`event`](Self::event), they also happen
-    /// when variables update and any other context or service structure that can be observed update.
+    /// when variables update and any other context or service structure that can be observed updates.
     fn update(&mut self, ctx: &mut WidgetContext);
 
     /// Called every time a layout update is needed.

zero-ui/properties/events/gesture.rs

@@ -5,7 +5,6 @@
 
 use super::event_property;
 use crate::core::context::WidgetContext;
-use crate::core::event::EventArgs;
 use crate::core::gesture::*;
 use crate::prelude::new_property::*;
 

zero-ui/properties/events/mouse.rs

@@ -6,7 +6,6 @@
 //! [`on_click`](fn@super::gesture::on_click) event.
 
 use super::event_property;
-use crate::core::event::EventArgs;
 use crate::core::mouse::*;
 
 event_property! {