[−][src]Module kas::event
Event handling
Event handling uses event messages, passed from the parent into a widget, with responses passed back to the parent. This model is simpler than that commonly used by GUI frameworks: widgets do not need a pointer to their parent and any result is pushed back up the call stack. The model allows type-safety while allowing user-defined result types.
We deliver events only on a "need to know" basis: typically, only one widget will receive an event.
Event delivery
Events can be addressed only to a WidgetId, so the first step (for
mouse and touch events) is to use kas::Layout::find_id to translate a
coordinate to a WidgetId.
Events then process from root to leaf. SendEvent::send is responsible
for forwarding an event to the appropriate child. Once the target widget is
reached, send (usually) calls Manager::handle_generic which may apply
some transformations to events, then calls Handler::handle on target
widget. Finally, a Response is emitted.
The Response enum has a few variants; most important is Msg(msg)
which passes a user-defined payload up to a parent widget. The
Unhandled(event) and Focus(rect) variants may be trapped by any parent
for secondary purposes, e.g. to adjust a ScrollRegion.
Mouse and touch events
Mouse events and touch events are unified: both have a "press" which starts somewhere, moves, and ends somewhere. The main difference concerns move events, which may occur with any number of mouse buttons pressed.
Motion and release events are only delivered when a "press grab" is active.
This is achieved by calling Manager::request_grab and allows receiving
both relative and absolute press coordinates.
A special "pan" grab allows receiving two-finger scroll/scale/rotate input.
Each touch event is considered independent. The mouse cursor and multiple fingers may all interact with different parts of a UI simultaneously. The same is partly true of keyboard input, though some actions force keyboard focus.
Pop-ups
When a pop-up widget is created, this forces keyboard focus to that widget
and receives a "weak" grab on press actions, meaning that the widget
receives this input first, but if returned via Response::Unhandled the
input passes immediately to the next target. This allows pop-up menus to
get first chance of handling input and to dismiss themselves when input is
for other widgets without blocking other widgets from accepting that input.
(This "weak grab" behaviour is intentional to align UI response with a
user's intuition that any visible non-grey part of the UI is interactive.)
Drawing
Widgets do not usually track input events for the purpose of drawn effects
such as mouse-hover. Instead, a widget calls WidgetCore::input_state
with a reference to the ManagerState (which is passed to
Layout::draw calls) in order to obtain an InputState instance.
Structs
| ConfigureManager | Helper used during widget configuration |
| Manager | Manager of event-handling and toolkit actions |
| ManagerState | Event manager state |
| ModifiersState | Represents the current state of the keyboard modifiers |
| UpdateHandle | An update handle |
Enums
| ControlKey | Control / Navigation key ( |
| CursorIcon | Describes the appearance of the mouse cursor. |
| Event | Events addressed to a widget |
| GrabMode | Controls the types of events delivered by |
| MouseButton | Describes a button of a mouse controller. |
| PressSource | Source of |
| Response | Response type from |
| ScrollDelta | Type used by |
| VirtualKeyCode | Symbolic name for a keyboard key. |
| VoidMsg | A void message |
Traits
| Handler | Event handling for a |
| SendEvent | Event routing |
Type Definitions
| VirtualKeyCodes | A type supporting a small number of key bindings |
| VoidResponse | Alias for |