Enum druid::Event

pub enum Event {
    WindowConnected,
    WindowCloseRequested,
    WindowDisconnected,
    WindowScale(Scale),
    WindowSize(Size),
    MouseDown(MouseEvent),
    MouseUp(MouseEvent),
    MouseMove(MouseEvent),
    Wheel(MouseEvent),
    KeyDown(KeyEvent),
    KeyUp(KeyEvent),
    Paste(Clipboard),
    Zoom(f64),
    Timer(TimerToken),
    AnimFrame(u64),
    Command(Command),
    Notification(Notification),
    ImeStateChange,
    Internal(InternalEvent),
}

An event, propagated downwards during event flow.

With two exceptions (Event::Command and Event::Notification, which have special considerations outlined in their own docs) each event corresponds to some user action or other message received from the platform.

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.

WindowCloseRequested

Sent to all widgets in a given window when the system requests to close the window.

If the event is handled (with set_handled), the window will not be closed. All widgets are given an opportunity to handle this event; your widget should not assume that the window will close just because this event is received; for instance, you should avoid destructive side effects such as cleaning up resources.

WindowDisconnected

Sent to all widgets in a given window when the system is going to close that window.

This event means the window will go away; it is safe to dispose of resources and do any other cleanup.

WindowScale(Scale)

Called when the window’s Scale changes.

This information can be used to switch between different resolution image assets.

WindowSize(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.

MouseDown(MouseEvent)

Called when a mouse button is pressed.

MouseUp(MouseEvent)

Called when a mouse button is released.

MouseMove(MouseEvent)

Called when the mouse is moved.

The MouseMove event is propagated to the active widget, if there is one, otherwise to hot widgets (see HotChanged). If a widget loses its hot status due to MouseMove then that specific MouseMove event is also still sent to that widget. However a widget can lose its hot status even without a MouseMove event, so make sure to also handle HotChanged if you care about the hot status.

The MouseMove 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 MouseMove handler, as MouseMove is only propagated to active or hot widgets.

Wheel(MouseEvent)

Called when the mouse wheel or trackpad is scrolled.

KeyDown(KeyEvent)

Called when a key is pressed.

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.

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.

AnimFrame(u64)

Called at the beginning of a new animation frame.

On the first frame when transitioning from idle to animating, interval will be 0. (This logic is presently per-window but might change to per-widget to make it more consistent). Otherwise it is in nanoseconds.

Receiving AnimFrame does not inherently mean a paint invocation will follow. If you want something actually painted you need to explicitly call request_paint or request_paint_rect.

If you do that, then the paint method will be called shortly after this event is finished. As a result, you should try to avoid doing anything computationally intensive in response to an AnimFrame event: it might make Druid miss the monitor’s refresh, causing lag or jerky animation.

You can request an AnimFrame via request_anim_frame.

Command(Command)

An event containing a Command to be handled by the widget.

Commands are messages, optionally with attached data, that can may be generated from a number of sources:

• If your application uses menus (either window or context menus) then the MenuItems in the menu will each correspond to a Command. When the menu item is selected, that Command will be delivered to the root widget of the appropriate window.
• If you are doing work in another thread (using an ExtEventSink) then Commands are the mechanism by which you communicate back to the main thread.
• Widgets and other Druid components can send custom Commands at runtime, via methods such as EventCtx::submit_command.

Notification(Notification)

A Notification from one of this widget’s descendants.

While handling events, widgets can submit notifications to be delivered to their ancestors immediately after they return.

If you handle a Notification, you should call EventCtx::set_handled to stop the notification from being delivered to further ancestors.

Special considerations

Notifications are slightly different from other events; they originate inside Druid, and they are delivered as part of the handling of another event. In this sense, they can sort of be thought of as an augmentation of an event; they are a way for multiple widgets to coordinate the handling of an event.

ImeStateChange

Sent to a widget when the platform may have mutated shared IME state.

This is sent to a widget that has an attached IME session anytime the platform has released a mutable lock on shared state.

This does not mean that any state has changed, but the widget should check the shared state, perform invalidation, and update Data as necessary.

Internal(InternalEvent)

Internal Druid event.

This should always be passed down to descendant WidgetPods.

Implementations

impl Event

pub fn should_propagate_to_hidden(&self) -> bool

Whether this event should be sent to widgets which are currently not visible and not accessible.

For example: the hidden tabs in a tabs widget are hidden whereas the non-visible widgets in a scroll are not, since you can bring them into view by scrolling.

This distinction between scroll and tabs is due to one of the main purposes of this method: determining which widgets are allowed to receive focus. As a rule of thumb a widget counts as hidden if it makes no sense for it to receive focus when the user presses the ‘tab’ key.

If a widget changes which children are hidden it must call children_changed.

See also LifeCycle::should_propagate_to_hidden.

pub fn is_pointer_event(&self) -> bool

Returns true if the event involves a cursor.

These events interact with the hot state and

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.