Struct EventCx 

pub struct EventCx<'a> { /* private fields */ }

Event handling context

This type supports access to ConfigCx and EventState via (recursive) Deref / DerefMut and to SizeCx via ConfigCx::size_cx.

Implementations

impl<'a> EventCx<'a>

pub fn request_key_focus(&mut self, target: Id, source: FocusSource)

Request keyboard input focus

When granted, the widget will receive Event::KeyFocus followed by Event::Key for each key press / release. Note that this disables translation of key events to Event::Command while key focus is active.

Since key focus requires selection focus, this method requests that too.

The source parameter is used by Event::SelFocus.

pub fn request_sel_focus(&mut self, target: Id, source: FocusSource)

Request selection focus

To prevent multiple simultaneous selections (e.g. of text) in the UI, only widgets with “selection focus” are allowed to select things. Selection focus is implied by character focus. Event::LostSelFocus is sent when selection focus is lost; in this case any existing selection should be cleared.

Selection focus is a pre-requisite for key focus and IME focus.

The source parameter is used by Event::SelFocus.

Selection focus implies navigation focus.

When key focus is lost, Event::LostSelFocus is sent.

pub fn replace_ime_focus( &mut self, target: Id, hint: ImeHint, purpose: ImePurpose, surrounding_text: Option<ImeSurroundingText>, )

Request Input Method Editor (IME) focus

IME focus requires selection focus (see EventCx::request_key_focus, EventCx::request_sel_focus). The request fails if this has not already been obtained (wait for Event::SelFocus or Event::KeyFocus before calling this method).

This method enables IME focus, replacing the existing focus. This should be used both to initially enable IME input and to replace the hint, purpose or surrounding_text.

Once enabled, target should receive Event::Ime events.

pub fn depress_with_key( &mut self, id: impl HasId, code: impl Into<Option<PhysicalKey>>, )

Visually depress a widget via a key code

When a button-like widget is activated by a key it may call this to ensure the widget is visually depressed until the key is released. The widget will not receive a notification of key-release but will be redrawn automatically.

Note that keyboard shortcuts and mnemonics should usually match against the “logical key”. PhysicalKey is used here since the the logical key may be changed by modifier keys.

Does nothing when code is None.

pub fn update_ime_surrounding_text( &self, target: &Id, surrounding_text: ImeSurroundingText, )

Update surrounding text used by Input Method Editor

impl<'a> EventCx<'a>

pub fn clear_nav_focus(&mut self)

Clear navigation focus

pub fn request_nav_focus(&mut self, id: Id, source: FocusSource)

Request navigation focus directly

If id already has navigation focus or navigation focus is disabled globally then nothing happens. If widget id supports navigation focus, then it should receive Event::NavFocus; if not then the first supporting ancestor will receive focus.

pub fn next_nav_focus( &mut self, target: impl Into<Option<Id>>, reverse: bool, source: FocusSource, )

Advance the navigation focus

If target == Some(id), this looks for the next widget from id (inclusive) which is navigable. Otherwise where some widget id has nav_focus this looks for the next navigable widget excluding id. If no reference is available, this instead looks for the first navigable widget.

If reverse, instead search for the previous or last navigable widget.

impl<'a> EventCx<'a>

pub fn set_mouse_over_icon(&mut self, icon: CursorIcon)

Set the pointer icon

This is normally called from Events::handle_mouse_over. In other cases, calling this method may be ineffective. The icon is automatically “unset” when the widget is no longer under the mouse.

See also EventCx::set_grab_icon: if a mouse grab (PressStart::grab) is active, its icon takes precedence.

pub fn set_grab_depress( &mut self, source: PressSource, target: Option<Id>, ) -> bool

Set a grab’s depress target

When a grab on mouse or touch input is in effect (PressStart::grab), the widget owning the grab may set itself or any other widget as depressed (“pushed down”). Each grab depresses at most one widget, thus setting a new depress target clears any existing target. Initially a grab depresses its owner.

This effect is purely visual. A widget is depressed when one or more grabs targets the widget to depress, or when a keyboard binding is used to activate a widget (for the duration of the key-press).

Assumption: this method will only be called by handlers of a grab (i.e. recipients of Event::PressStart after initiating a successful grab, Event::PressMove or Event::PressEnd).

Queues a redraw and returns true if the depress target changes, otherwise returns false.

pub fn set_grab_icon(&mut self, id: &Id, icon: CursorIcon)

Update the mouse pointer icon used during a grab

This only succeeds if widget id has an active mouse-grab (see PressStart::grab). The icon will be reset when the mouse-grab ends.

impl<'a> EventCx<'a>

pub fn last_child(&self) -> Option<usize>

Get the index of the last child visited

This is only used when unwinding (traversing back up the widget tree), and returns the index of the child last visited. E.g. when Events::handle_messages is called, this method returns the index of the child which submitted the message (or whose descendant did). Otherwise this returns None (including when the widget itself is the submitter of the message).

pub fn push<M: Debug + 'static>(&mut self, msg: M)

Push a message to the stack

The message is first type-erased by wrapping with Erased, then pushed to the stack.

The message may be popped or peeked from Events::handle_messages by the widget itself, its parent, or any ancestor.

If not handled during the widget tree traversal and a target is set for M then msg is sent to this target.

pub fn push_erased(&mut self, msg: Erased)

Push a type-erased message to the stack

This is a lower-level variant of Self::push.

pub fn has_msg(&self) -> bool

True if the message stack is non-empty

pub fn try_pop<M: Debug + 'static>(&mut self) -> Option<M>

Try popping the last message from the stack with the given type

This method may be called from Events::handle_messages.

pub fn try_peek<M: Debug + 'static>(&self) -> Option<&M>

Try observing the last message on the stack without popping

This method may be called from Events::handle_messages.

pub fn peek_debug(&self) -> Option<&dyn Debug>

Debug the last message on the stack, if any

pub fn msg_op_count(&self) -> usize

Get the message stack operation count

This is incremented every time the message stack is changed, thus can be used to test whether a message handler did anything.

pub fn set_scroll(&mut self, scroll: Scroll)

Set a scroll action

When setting Scroll::Rect, use the widget’s own coordinate space.

Note that calling this method has no effect on the widget itself, but affects parents via their Events::handle_scroll method.

impl<'a> EventCx<'a>

pub fn add_dataless_window( &mut self, window: Window<()>, modal: bool, ) -> WindowId

Add a data-less window

This method may be used to attach a new window to the UI at run-time. This method supports windows which do not take data; see also Self::add_window.

Adding the window is infallible. Opening the new window is theoretically fallible (unlikely assuming a window has already been opened).

If modal, then the new window is considered owned by this window (the window the calling widget belongs to), preventing interaction with this window until the new window has been closed. Note: this is mostly unimplemented; see Window::set_modal_with_parent.

pub fn add_window<Data: AppData>( &mut self, window: Window<Data>, modal: bool, ) -> WindowId

Add a window able to access top-level app data

This method may be used to attach a new window to the UI at run-time. See also Self::add_dataless_window for a variant which does not require a Data parameter.

Requirement: the type Data must match the type of data passed to the Runner and used by other windows. If not, a run-time error will result.

Adding the window is infallible. Opening the new window is theoretically fallible (unlikely assuming a window has already been opened).

If modal, then the new window is considered owned by this window (the window the calling widget belongs to), preventing interaction with this window until the new window has been closed. Note: this is mostly unimplemented; see Window::set_modal_with_parent.

pub fn close_window(&mut self, id: WindowId)

Close a window or pop-up

Navigation focus will return to whichever widget had focus before the popup was open.

pub fn drag_window(&self)

Enable window dragging for current click

This calls winit::window::Window::drag_window. Errors are ignored.

pub fn drag_resize_window(&self, direction: ResizeDirection)

Enable window resizing for the current click

This calls winit::window::Window::drag_resize_window. Errors are ignored.

pub fn get_clipboard(&mut self) -> Option<String>

Attempt to get clipboard contents

In case of failure, paste actions will simply fail. The implementation may wish to log an appropriate warning message.

pub fn set_clipboard(&mut self, content: String)

Attempt to set clipboard contents

pub fn has_primary(&self) -> bool

True if the primary buffer is enabled

pub fn get_primary(&mut self) -> Option<String>

Get contents of primary buffer

Linux has a “primary buffer” with implicit copy on text selection and paste on middle-click. This method does nothing on other platforms.

pub fn set_primary(&mut self, content: String)

Set contents of primary buffer

Linux has a “primary buffer” with implicit copy on text selection and paste on middle-click. This method does nothing on other platforms.

pub fn winit_window(&self) -> Option<&dyn Window>

Directly access Winit Window

This is a temporary API, allowing e.g. to minimize the window.

impl<'a> EventCx<'a>

pub fn draw_shared(&mut self) -> &mut dyn DrawShared

Get a DrawShared

pub fn change_config(&mut self, msg: ConfigMsg)

Update configuration data

pub fn with_config(&mut self, f: impl FnOnce(&WindowConfig) -> ConfigAction)

Update configuration data using a closure

pub fn exit(&mut self)

Terminate the GUI

Methods from Deref<Target = ConfigCx<'a>>

pub fn register_nav_fallback(&mut self, id: Id)

Sets the fallback recipient of Event::Command

Where a key-press translates to a Command, this is first sent to widgets with applicable key, selection and/or navigation focus as an Event::Command. If this event goes unhandled and a fallback recipient is set using this method, then this fallback recipient will be sent the same event.

There may be one fallback recipient per window; do not use an Id from another window. If this method is called multiple times, the last such call succeeds.

pub fn size_cx<'b>(&'b mut self) -> SizeCx<'b>

where 'a: 'b,

Access a SizeCx

pub fn configure(&mut self, widget: Node<'_>, id: Id)

Configure a widget

All widgets must be configured after construction; see widget lifecycle and configuration. Widgets must always be sized after configuration.

Assigns id to the widget. This must be valid and is usually constructed with Events::make_child_id.

pub fn update(&mut self, widget: Node<'_>)

Update a widget

All widgets must be updated after input data changes; see update.

pub fn set_disabled(&mut self, target: Id, disable: bool)

Set/unset a widget as disabled

Disabled status applies to all descendants and blocks reception of events (Unused is returned automatically when the recipient or any ancestor is disabled).

Disabling a widget clears navigation, selection and key focus when the target is disabled, and also cancels press/pan grabs.

pub fn set_send_target_for<M: Debug + 'static>(&mut self, id: Id)

Set a target for messages of a specific type when sent to Id::default()

Messages of this type sent to Id::default() from any window will be sent to id.

pub fn redraw(&mut self)

Notify that a widget must be redrawn

“The current widget” is inferred from the widget tree traversal through which the EventCx is made accessible. The resize is handled locally during the traversal unwind if possible.

pub fn resize(&mut self)

Require that the current widget (and its descendants) be resized

“The current widget” is inferred from the widget tree traversal through which the EventCx is made accessible. The resize is handled locally during the traversal unwind if possible.

Methods from Deref<Target = EventState>

pub fn has_input_focus(&self, w_id: &Id) -> Option<bool>

Get whether this widget has input focus

Return values:

• None if the widget does not have selection focus
• Some(false) if the widget has selection focus but not keyboard or IME focus
• Some(true) if the widget has keyboard and/or IME focus

pub fn modifiers(&self) -> ModifiersState

Get the current modifier state

pub fn set_ime_cursor_area(&mut self, target: &Id, rect: Rect)

Set IME cursor area

This should be called after receiving Event::Ime(Ime::Enabled), and any time that the rect parameter changes, until Event::Ime(Ime::Disabled) is received.

This sets the text cursor’s area, rect, relative to the widget’s own coordinate space. If never called, then the widget’s whole rect is used.

This does nothing if target does not have IME-enabled input focus.

pub fn cancel_ime_focus(&mut self, target: &Id)

Explicitly clear Input Method Editor focus on target

This method may be used to disable IME focus while retaining selection focus. IME focus is lost automatically when selection focus is lost.

pub fn has_nav_focus(&self, w_id: &Id) -> bool

Get whether this widget has navigation focus

pub fn nav_focus(&self) -> Option<&Id>

Get the current navigation focus, if any

This is the widget selected by navigating the UI with the Tab key.

Note: changing navigation focus (e.g. via EventCx::clear_nav_focus, EventCx::request_nav_focus or EventCx::next_nav_focus) does not immediately affect the result of this method.

pub fn is_depressed(&self, w_id: &Id) -> bool

Check whether the given widget is visually depressed

pub fn is_under_mouse(&self, w_id: &Id) -> bool

Get whether the widget is under the mouse pointer

pub fn any_grab_on(&self, id: &Id) -> bool

Returns true if there is a mouse or touch grab on id or any descendant of id

pub fn press_velocity(&self, source: PressSource) -> Option<Vec2>

Get velocity of the mouse pointer or a touch

The velocity is calculated at the time this method is called using existing samples of motion.

Where the source is a mouse this always succeeds. For touch events this requires an active grab and is not guaranteed to succeed; currently only a limited number of presses with mode GrabMode::Grab are tracked for velocity.

pub fn send<M: Debug + 'static>(&mut self, id: Id, msg: M)

Send a message to id

When calling this method, be aware that some widgets use an inner component to handle events, thus calling with the outer widget’s id may not have the desired effect. Tile::try_probe and EventCx::next_nav_focus are usually able to find the appropriate event-handling target.

This uses a tree traversal as with event handling, thus ancestors will have a chance to handle an unhandled event and any messages on the stack after their child.

Special cases sent as an Event

When M is Command, this will send Event::Command to the widget.

When M is ScrollDelta, this will send Event::Scroll to the widget.

Other messages

The message is pushed to the message stack. The target widget may pop or peek the message from Events::handle_messages.

Send target

The target id may be under another window. In this case, sending may be delayed slightly.

If id = Id::default() and a send target has been assigned for M, then msg will be sent to that target.

If id identifies a widget, that widget must be configured but does not need to be sized.

If id does not resolve a widget, the message is dropped with only a DEBUG log message of the form _replay: $WIDGET cannot find path to $ID. This is not considered an error since it happens frequently (e.g. any widget using asynchronous loading sends itself a message; if the view changes before loading completes then that widget may no longer be accessible or no longer exist).

Ordering and failure

Messages sent via send and send_erased should be received in the same order sent relative to other messages sent from the same window via these methods.

Message delivery may fail for widgets not currently visible. This is dependent on widgets implementation of Widget::child_node (e.g. in the case of virtual scrolling, the target may have scrolled out of range).

pub fn send_erased(&mut self, id: Id, msg: Erased)

Push a type-erased message to the stack

This is a lower-level variant of Self::send.

pub fn send_async<Fut, M>(&mut self, id: Id, fut: Fut)

where Fut: IntoFuture<Output = M> + 'static, M: Debug + 'static,

Send a message to id via a Future

The future is polled after event handling and after drawing and is able to wake the event loop. This future is executed on the main thread; for high-CPU tasks use Self::send_spawn instead.

The future must resolve to a message on completion. Its message is then sent to id via stack traversal identically to Self::send.

Cancellation, ordering and failure

Futures passed to these methods should only be cancelled if they fail to complete before the window is closed, and even in this case will be polled at least once.

Messages sent via send_async, send_async_erased and send_spawn may be received in any order.

Message delivery may fail for widgets not currently visible. This is dependent on widgets implementation of Widget::child_node (e.g. in the case of virtual scrolling, the target may have scrolled out of range).

pub fn send_async_erased<Fut>(&mut self, id: Id, fut: Fut)

where Fut: IntoFuture<Output = Erased> + 'static,

Send a type-erased message to id via a Future

This is a low-level variant of Self::send_async.

pub fn send_spawn<Fut, M>(&mut self, id: Id, fut: Fut)

where Fut: IntoFuture<Output = M> + 'static, Fut::IntoFuture: Send, M: Debug + Send + 'static,

Available on crate feature spawn only.

Spawn a task, run on a thread pool

The future is spawned to a thread-pool before the event-handling loop sleeps, and is able to wake the loop on completion. Tasks involving significant CPU work should use this method over Self::send_async.

This method is simply a wrapper around async_global_executor::spawn and Self::send_async; if a different multi-threaded executor is available, that may be used instead. See also async_global_executor documentation of configuration.

pub fn request_timer(&mut self, id: Id, handle: TimerHandle, delay: Duration)

Schedule a timed update

Widget updates may be used for delayed action. For animation, prefer to use Draw::animate or Self::request_frame_timer.

Widget id will receive Event::Timer with this handle at approximately time = now + delay (or possibly a little later due to frame-rate limiters and processing time).

Requesting an update with delay == 0 is valid, except from an Event::Timer handler (where it may cause an infinite loop).

Multiple timer requests with the same id and handle are merged (see TimerHandle documentation).

pub fn request_frame_timer(&mut self, id: Id, handle: TimerHandle)

Schedule a frame timer update

Widget id will receive Event::Timer with this handle either before or soon after the next frame is drawn.

This may be useful for animations which mutate widget state. Animations which don’t mutate widget state may use Draw::animate instead.

It is expected that handle.earliest() == true (style guide).

pub fn platform(&self) -> Platform

Get the platform

pub fn window_has_focus(&self) -> bool

True when the window has focus

pub fn is_disabled(&self, w_id: &Id) -> bool

Check whether a widget is disabled

A widget is disabled if any ancestor is.

pub fn config(&self) -> &WindowConfig

Access configuration data

All widgets will be reconfigured if configuration data changes.

pub fn config_enable_pan(&self, source: PressSource) -> bool

Is mouse panning enabled?

pub fn config_enable_mouse_text_pan(&self) -> bool

Is mouse text panning enabled?

pub fn config_test_pan_thresh(&self, dist: Offset) -> bool

Test pan threshold against config, adjusted for scale factor

Returns true when dist is large enough to switch to pan mode.

pub fn redraw(&mut self, id: impl HasId)

Notify that a widget must be redrawn

This method is designed to support partial redraws though these are not currently implemented. See also Self::action_redraw.

pub fn region_moved(&mut self)

Notify that widgets under self may have moved

This updates the widget(s) under mouse and touch events.

pub fn close_own_window(&mut self)

Request that the window be closed

pub fn action_moved(&mut self, action: impl Into<Option<ActionMoved>>)

Notify of an ActionMoved or Option<ActionMoved>

pub fn action_redraw(&mut self, action: impl Into<Option<ActionRedraw>>)

Notify of an ActionRedraw or Option<ActionRedraw>

This will force a redraw of the whole window. See also Self::redraw.

Trait Implementations

impl<'a> Deref for EventCx<'a>

type Target = ConfigCx<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> DerefMut for EventCx<'a>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.