kas_core/event/
mod.rs

1// Licensed under the Apache License, Version 2.0 (the "License");
2// you may not use this file except in compliance with the License.
3// You may obtain a copy of the License in the LICENSE-APACHE file or at:
4//     https://www.apache.org/licenses/LICENSE-2.0
5
6//! Event handling
7//!
8//! ## Event handling model
9//!
10//! Note: widgets are represented as an acyclic tree, with the *root* at the
11//! "top" of the tree. Each tree node is a [`Widget`] and has an [`Id`].
12//! An [`Id`] represents a *path* and may be used to find the most
13//! direct root from the root to the target.
14//!
15//! An [`Event`] is sent to a target widget as follows:
16//!
17//! 1.  Determine the target's [`Id`]. For example, this may be
18//!     the [`nav_focus`](EventState::nav_focus) or may be determined from
19//!     from mouse/touch coordinates by calling [`try_probe`](crate::Layout::try_probe).
20//! 2.  If the target is [disabled](EventState::is_disabled), then find the
21//!     top-most ancestor which is disabled and make that the target, but
22//!     inhibit calling of [`Events::handle_event`] on this widget (but still
23//!     unwind, calling [`Events::handle_event`] on ancestors)).
24//! 3.  Traverse *down* the widget tree from its root to the target according to
25//!     the [`Id`].
26//! 4.  In the normal case (when the target is not disabled and the event is
27//!     not stolen), [`Events::handle_event`] is called on the target.
28//! 5.  If the message stack is not empty, call [`Events::handle_messages`] on
29//!     the current node.
30//! 6.  Unwind, traversing back *up* the widget tree (towards the root).
31//!     On each node (excluding the target),
32//!
33//!     -   If a non-empty scroll action is [set](EventCx::set_scroll),
34//!         call [`Events::handle_scroll`]
35//!     -   If the event has not yet been [used](Used),
36//!         call [`Events::handle_event`]
37//!     -   If the message stack is non-empty (see [`EventCx::push`]),
38//!         call [`Events::handle_messages`].
39//! 7.  If the message stack is not empty, call
40//!     [`AppData::handle_messages`](crate::runner::AppData::handle_messages).
41//! 8.  Clear any messages still on the message stack, printing a warning to the
42//!     log. Messages *should* be handled during unwinding, though not doing so
43//!     is safe (and possibly useful during development).
44//!
45//! ### Pop-ups
46//!
47//! When a pop-up widget is created, the pop-up's parent takes priority for
48//! "press" (mouse / touch) input as well as receiving keyboard focus.
49//!
50//! If this input is unhandled, the pop-up is automatically closed and the event
51//! is re-sent to the next candidate, allowing handling of e.g. mouse clicks on
52//! widgets under a menu. This should be intuitive: UI which is in focus and
53//! not greyed-out should be interactive.
54//!
55//! [`Id`]: crate::Id
56
57pub mod components;
58mod config_cx;
59mod cx;
60mod event;
61mod response;
62
63pub use smol_str::SmolStr;
64pub use winit::event::{ElementState, KeyEvent, MouseButton};
65pub use winit::keyboard::{Key, ModifiersState, NamedKey, PhysicalKey};
66pub use winit::window::{CursorIcon, ImePurpose}; // used by Key
67
68#[allow(unused)] use crate::{Events, Widget};
69pub use config_cx::ConfigCx;
70pub use cx::*;
71pub use event::*;
72pub use response::{IsUsed, Scroll, Unused, Used};
kas_core/event/mod.rs

kas_core/event/
mod.rs
