Struct kas::event::EventState

pub struct EventState { /* private fields */ }

Event context state

This struct encapsulates window-specific event-handling state and handling. Most operations are only available via a EventCx handle, though some are available on this struct.

Besides event handling, this struct also configures widgets.

Some methods are intended only for usage by graphics and platform backends and are hidden from generated documentation unless the internal_doc feature is enabled. Only winit events are currently supported; changes will be required to generalise this.

Implementations

impl EventState

Public API

pub fn platform(&self) -> Platform

Get the platform

pub fn window_has_focus(&self) -> bool

True when the window has focus

pub fn show_access_labels(&self) -> bool

True when access key labels should be shown

(True when Alt is held and no widget has character focus.)

This is a fast check.

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

Get whether this widget has (key_focus, sel_focus)

• key_focus: implies this widget receives keyboard input
• sel_focus: implies this widget is allowed to select things

Note that key_focus implies sel_focus.

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

Get whether this widget has navigation focus

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

Get whether the widget is under the mouse cursor

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

Get whether widget id or any of its descendants are under the mouse cursor

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

Check whether the given widget is visually depressed

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 modifiers(&self) -> ModifiersState

Get the current modifier state

pub fn config(&self) -> &WindowConfig

Access event-handling configuration

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 change_config(&mut self, msg: ChangeConfig)

Update event configuration

pub fn set_disabled(&mut self, w_id: Id, state: 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).

pub fn request_timer(&mut self, id: Id, payload: u64, delay: Duration)

Schedule a timed update

Widget updates may be used for animation and timed responses. See also Draw::animate for animation.

Widget id will receive Event::Timer with this payload 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 payload are merged (choosing the earliest time).

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

Notify that a widget must be redrawn

This is equivalent to calling Self::action with Action::REDRAW.

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

Notify that a widget must be resized

This is equivalent to calling Self::action with Action::RESIZE.

pub fn region_moved(&mut self)

Notify that widgets under self may have moved

pub fn exit(&mut self)

Terminate the GUI

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

Notify that a Action action should happen

This causes the given action to happen after event handling.

Whenever a widget is added, removed or replaced, a reconfigure action is required. Should a widget’s size requirements change, these will only affect the UI after a reconfigure action.

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

Attempts to set a fallback to receive Event::Command

In case a navigation key is pressed (see Command) but no widget has navigation focus, then, if a fallback has been set, that widget will receive the key via Event::Command.

Only one widget can be a fallback, and the first to set itself wins. This is primarily used to allow scroll-region widgets to respond to navigation keys when no widget has focus.

pub fn new_access_layer(&mut self, id: Id, alt_bypass: bool)

Add a new access key layer

This method constructs a new “layer” for access keys: any keys added via EventState::add_access_key to a widget which is a descentant of (or equal to) id will only be active when that layer is active.

This method should only be called by parents of a pop-up: layers over the base layer are only activated by an open pop-up.

If alt_bypass is true, then this layer’s access keys will be active even without Alt pressed (but only highlighted with Alt pressed).

pub fn enable_alt_bypass(&mut self, id: &Id, alt_bypass: bool)

Enable alt_bypass for layer

This may be called by a child widget during configure to enable or disable alt-bypass for the access-key layer containing its access keys. This allows access keys to be used as shortcuts without the Alt key held. See also EventState::new_access_layer.

pub fn add_access_key(&mut self, id: &Id, key: Key)

Adds an access key for a widget

An access key (also known as mnemonic) is a shortcut key able to directly open menus, activate buttons, etc. A user triggers the key by pressing Alt+Key, or (if alt_bypass is enabled) by simply pressing the key. The widget with this id then receives Command::Activate.

Note that access keys may be automatically derived from labels: see crate::text::AccessString.

Access keys are added to the layer with the longest path which is an ancestor of id. This usually means that if the widget is part of a pop-up, the key is only active when that pop-up is open. See EventState::new_access_layer.

This should only be called from Events::configure.

pub fn depress_with_key(&mut self, id: Id, code: 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.

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.

The source parameter is used by Event::SelFocus.

Key focus implies sel focus (see Self::request_sel_focus) and navigation focus.

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.

The source parameter is used by Event::SelFocus.

Selection focus implies navigation focus.

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

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 (Press::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).

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

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

Returns true if id or any descendant has a mouse or touch grab

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 Self::clear_nav_focus, Self::set_nav_focus or Self::next_nav_focus) does not immediately affect the result of this method.

pub fn clear_nav_focus(&mut self)

Clear navigation focus

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

Set navigation focus directly

If id already has navigation focus or navigation focus is disabled globally then nothing happens, otherwise widget id should receive Event::NavFocus.

Normally, Events::navigable will be true for widget id but this is not checked or required. For example, a ScrollLabel can receive focus on text selection with the mouse.

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 (Events::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.

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

Set the cursor icon

This is normally called when handling Event::MouseHover. In other cases, calling this method may be ineffective. The cursor is automatically “unset” when the widget is no longer hovered.

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

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

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

Asynchronously push a message to the stack 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::push_spawn instead.

The future must resolve to a message on completion. This message is pushed to the message stack as if it were pushed with EventCx::push from widget id, allowing this widget or any ancestor to handle it in Events::handle_messages.

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

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

Asynchronously push a type-erased message to the stack via a Future

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

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

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

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

This method is simply a wrapper around [async_global_executor::spawn] and Self::push_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_update(&mut self, id: Id, reconf: bool)

Request update and optionally configure to widget id

If reconf, widget id will be configured (includes update), otherwise id will only be updated.

impl EventState

This impl block contains no items.

internals