Struct kas_core::event::EventState

pub struct EventState { /* private fields */ }

Event manager state

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

Besides event handling, this struct also configures widgets.

Some methods are intended only for usage by KAS shells and are hidden from 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 window_has_focus(&self) -> bool

True when the window has focus

pub fn show_accel_labels(&self) -> bool

True when accelerator key labels should be shown

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

This is a fast check.

pub fn has_char_focus(&self, w_id: &WidgetId) -> (bool, bool)

Get whether this widget has (char_focus, sel_focus)

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

Note that char_focus implies sel_focus.

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

Get whether this widget has keyboard navigation focus

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

Get whether the widget is under the mouse cursor

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

Check whether the given widget is visually depressed

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

Set/unset a widget as disabled

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

pub fn request_update(
    &mut self,
    id: WidgetId,
    payload: u64,
    delay: Duration,
    first: bool
)

Schedule an update

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

Widget w_id will receive Event::TimerUpdate 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::TimerUpdate handler (where it may cause an infinite loop).

If multiple updates with the same id and payload are requested, these are merged (using the earliest time if first is true).

pub fn redraw(&mut self, _id: WidgetId)

Notify that a widget must be redrawn

Note: currently, only full-window redraws are supported, thus this is equivalent to: mgr.send_action(TkAction::REDRAW);

pub fn send_action(&mut self, action: TkAction)

Notify that a TkAction action should happen

This causes the given action to happen after event handling.

Calling mgr.send_action(action) is equivalent to *mgr |= action.

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: WidgetId)

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_accel_layer(&mut self, id: WidgetId, alt_bypass: bool)

Add a new accelerator key layer

This method constructs a new “layer” for accelerator keys: any keys added via EventState::add_accel_keys 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 accelerator keys will be active even without Alt pressed (but only highlighted with Alt pressed).

pub fn enable_alt_bypass(&mut self, id: &WidgetId, 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 accel-key layer containing its accel keys. This allows accelerator keys to be used as shortcuts without the Alt key held. See also EventState::new_accel_layer.

pub fn add_accel_keys(&mut self, id: &WidgetId, keys: &[VirtualKeyCode])

Adds an accelerator key for a widget

An accelerator key 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 accelerator keys may be automatically derived from labels: see crate::text::AccelString.

Accelerator 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_accel_layer.

This should only be called from Widget::configure.

pub fn request_char_focus(&mut self, id: WidgetId) -> bool

Request character-input focus

Returns true on success or when the widget already had char focus.

Character data is sent to the widget with char focus via Event::ReceivedCharacter and Event::Command.

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

When char focus is lost, Event::LostCharFocus is sent.

pub fn request_sel_focus(&mut self, id: WidgetId) -> bool

Request selection focus

Returns true on success or when the widget already had sel 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 implies navigation focus.

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

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

Set a grab’s depress target

When a grab on mouse or touch input is in effect (EventMgr::grab_press), 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: &WidgetId) -> bool

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

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

Get the current keyboard navigation focus, if any

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

pub fn clear_nav_focus(&mut self)

Clear keyboard navigation focus

pub fn set_nav_focus(&mut self, id: WidgetId, key_focus: bool)

Set the keyboard navigation focus directly

Normally, Widget::navigable will be true for the specified widget, but this is not required, e.g. a ScrollLabel can receive focus on text selection with the mouse. (Currently such widgets will receive events like any other with nav focus, but this may change.)

The target widget, if not already having navigation focus, will receive Event::NavFocus with key_focus as the payload. This boolean should be true if focussing in response to keyboard input, false if reacting to mouse or touch input.

pub fn set_cursor_icon(&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.

If a mouse grab (EventMgr::grab_press) is active, its icon takes precedence.

Trait Implementations

impl BitOrAssign<TkAction> for EventState

fn bitor_assign(&mut self, action: TkAction)

Performs the |= operation.

impl Debug for EventState

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

Formats the value using the given formatter.