Module kas::event[−][src]

Expand description

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 crate::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.