Enum druid::Event

pub enum Event {
    WindowConnected,
    Size(Size),
    MouseDown(MouseEvent),
    MouseUp(MouseEvent),
    MouseMoved(MouseEvent),
    KeyDown(KeyEvent),
    KeyUp(KeyEvent),
    Paste(Clipboard),
    Wheel(WheelEvent),
    Zoom(f64),
    Timer(TimerToken),
    Command(Command),
    TargetedCommand(Target, Command),
}

An event, propagated downwards during event flow.

Events are things that happen that can change the state of widgets. An important category is events plumbed from the platform windowing system, which includes mouse and keyboard events, but also (in the future) status changes such as window focus changes.

Events can also be higher level concepts indicating state changes within the widget hierarchy, for example when a widget gains or loses focus or "hot" (also known as hover) status.

Events are a key part of what is called "event flow", which is basically the propagation of an event through the widget hierarchy through the event widget method. A container widget will generally pass the event to its children, mediated through the WidgetPod container, which is where most of the event flow logic is applied (especially the decision whether or not to propagate).

This enum is expected to grow considerably, as there are many, many different kinds of events that are relevant in a GUI.

Variants

WindowConnected

Sent to all widgets in a given window when that window is first instantiated.

This should always be the first Event received, although widgets will receive LifeCycle::WidgetAdded first.

Widgets should handle this event if they need to do some addition setup when a window is first created.

Size(Size)

Called on the root widget when the window size changes.

Discussion: it's not obvious this should be propagated to user widgets. It is propagated through the RootWidget and handled in the WindowPod, but after that it might be considered better to just handle it in layout.

The propagation logic of "just the root" requires a little bit of complexity and state in EventCtx, so if it's not useful it should be removed.

MouseDown(MouseEvent)

Called when a mouse button is pressed.

MouseUp(MouseEvent)

Called when a mouse button is released.

MouseMoved(MouseEvent)

Called when the mouse is moved.

The MouseMoved event is propagated to the active widget, if there is one, otherwise to hot widgets (see HotChanged).

The MouseMoved event is also the primary mechanism for widgets to set a cursor, for example to an I-bar inside a text widget. A simple tactic is for the widget to unconditionally call set_cursor in the MouseMoved handler, as MouseMove is only propagated to active or hot widgets.

KeyDown(KeyEvent)

Called when a key is pressed.

Note: the intent is for each physical key press to correspond to a single KeyDown event. This is sometimes different than the raw events provided by the platform. In particular, Windows sends one or both of WM_KEYDOWN (a raw key code) and WM_CHAR (the Unicode value), depending on the actual key.

KeyUp(KeyEvent)

Called when a key is released.

Because of repeat, there may be a number KeyDown events before a corresponding KeyUp is sent.

Paste(Clipboard)

Called when a paste command is received.

Wheel(WheelEvent)

Called when the mouse wheel or trackpad is scrolled.

Zoom(f64)

Called when the trackpad is pinched.

The value is a delta.

Timer(TimerToken)

Called on a timer event.

Request a timer event through EventCtx::request_timer(). That will cause a timer event later.

Note that timer events from other widgets may be delivered as well. Use the token returned from the request_timer() call to filter events more precisely.

Command(Command)

Called with an arbitrary Command, submitted from elsewhere in the application.

Commands can be issued when the user triggers a menu item or an application-level hotkey, or they can be created dynamically by Widgets, at runtime, with EventCtx::submit_command.

TargetedCommand(Target, Command)

A command still in the process of being dispatched. This is an internal event and should generally not be handled directly by widgets, but is important for containers to dispatch to their children.

Methods

impl Event

pub fn transform_scroll(
    &self,
    offset: Vec2,
    viewport: Rect,
    force: bool
) -> Option<Event>

Transform the event for the contents of a scrolling container.

the force flag is used to ensure an event is delivered even if the cursor is out of the viewport, such as if the contents are active or hot.

Trait Implementations

impl Clone for Event

fn clone(&self) -> Event

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Event

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.