Module kas::event

Event handling

Event handling model

Note: widgets are represented as an acyclic tree, with the root at the “top” of the tree. Each tree node is a Widget and has an Id. An Id represents a path and may be used to find the most direct root from the root to the target.

An Event is sent to a target widget as follows:

1. Determine the target’s Id. For example, this may be the nav_focus or may be determined from from mouse/touch coordinates by calling find_id.

2. If the target is disabled, then find the top-most ancestor which is disabled and make that the target, but inhibit calling of Events::handle_event on this widget (but still unwind, calling Events::handle_event on ancestors)).

3. Traverse down the widget tree from its root to the target according to the Id. On each node (excluding the target),

   • Call Events::steal_event; if this method “steals” the event, skip to step 5.

4. In the normal case (when the target is not disabled and the event is not stolen), Events::handle_event is called on the target.

5. If the message stack is not empty, call Events::handle_messages on the current node.

6. Unwind, traversing back up the widget tree (towards the root). On each node (excluding the target),

   • If a non-empty scroll action is set, call Events::handle_scroll
   • If the event has not yet been used, call Events::handle_event
   • If the message stack is non-empty (see EventCx::push), call Events::handle_messages.

7. If the message stack is not empty, call AppData::handle_messages.

8. Clear any messages still on the message stack, printing a warning to the log. Messages should be handled during unwinding, though not doing so is safe (and possibly useful during development).

Pop-ups

When a pop-up widget is created, the pop-up’s parent takes priority for “press” (mouse / touch) input as well as receiving keyboard focus.

If this input is unhandled, the pop-up is automatically closed and the event is re-sent to the next candidate, allowing handling of e.g. mouse clicks on widgets under a menu. This should be intuitive: UI which is in focus and not greyed-out should be interactive.

Modules

• components
  Event handling components
• config
  Event handling configuration

Structs

• Config
  Event handling configuration
• ConfigCx
  Widget configuration and update context
• EventCx
  Event handling context
• EventState
  Event context state
• GrabBuilder
  Bulider pattern (see Press::grab)
• KeyEvent
  Describes a keyboard input targeting a window.
• ModifiersState
  Represents the current state of the keyboard modifiers
• Press
  Details of press events
• SmolStr
  A SmolStr is a string type that has the following properties:

Enums

• Command
  Command input (Event::Command)
• CursorIcon
  Describes the appearance of the (usually mouse) cursor icon.
• ElementState
  Describes the input state of a key.
• Event
  Events addressed to a widget
• FocusSource
  Reason that navigation focus is received
• GrabMode
  Controls the types of events delivered by Press::grab
• IsUsed
  Return type of event-handling methods
• Key
  Key represents the meaning of a keypress.
• MouseButton
  Describes a button of a mouse controller.
• NamedKey
  A Key::Named value
• PhysicalKey
  Represents the location of a physical key.
• PressSource
  Source of EventChild::Press
• ResizeDirection
  Defines the orientation that a window resize will be performed.
• Scroll
  Request to / notification of scrolling from a child
• ScrollDelta
  Type used by Event::Scroll