Struct kas::event::Manager

#[must_use]pub struct Manager<'a> { /* fields omitted */ }

Manager of event-handling and toolkit actions

A Manager is in fact a handle around ManagerState and [TkWindow] in order to provide a convenient user-interface during event processing.

It exposes two interfaces: one aimed at users implementing widgets and UIs and one aimed at toolkit "frontends". The latter is hidden from documentation unless the internal_doc feature is enabled.

Implementations

impl<'a> Manager<'a>

pub fn handle_generic<W: ?Sized>(
    widget: &mut W,
    mgr: &mut Manager<'_>,
    event: Event
) -> Response<<W as Handler>::Msg> where
    W: Handler, 

Generic event simplifier

This is a free function often called from SendEvent::send to simplify certain events and then invoke Handler::handle.

impl<'a> Manager<'a>

Public API (around toolkit functionality)

pub fn modifiers(&self) -> ModifiersState

Get the current modifier state

pub fn update_on_timer(&mut self, duration: Duration, w_id: WidgetId)

Schedule an update

Widgets requiring animation should schedule an update; as a result, Event::TimerUpdate will be sent, roughly at time now + duration.

Timings may be a few ms out, but should be sufficient for e.g. updating a clock each second. Very short positive durations (e.g. 1ns) may be used to schedule an update on the next frame. Frames should in any case be limited by vsync, avoiding excessive frame rates.

This may be called from WidgetConfig::configure or from an event handler. Note that previously-scheduled updates are cleared when widgets are reconfigured.

pub fn update_on_handle(&mut self, handle: UpdateHandle, w_id: WidgetId)

Subscribe to an update handle

All widgets subscribed to an update handle will be sent Event::HandleUpdate when Manager::trigger_update is called with the corresponding handle.

This should be called from WidgetConfig::configure.

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

Notify that a widget must be redrawn

Currently the entire window is redrawn on any redraw request and the WidgetId is ignored. In the future partial redraws may be used.

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.

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 pop_action(&mut self) -> TkAction

Get the current TkAction, replacing with None

The caller is responsible for ensuring the action is handled correctly; generally this means matching only actions which can be handled locally and downgrading the action, adding the result back to the Manager.

pub fn add_popup(&mut self, popup: Popup) -> WindowId

Add an overlay (pop-up)

A pop-up is a box used for things like tool-tips and menus which is drawn on top of other content and has focus for input.

Depending on the host environment, the pop-up may be a special type of window without borders and with precise placement, or may be a layer drawn in an existing window.

A pop-up may be closed by calling Manager::close_window with the WindowId returned by this method.

pub fn add_window(&mut self, widget: Box<dyn Window>) -> WindowId

Add a window

Typically an application adds at least one window before the event-loop starts (see kas_wgpu::Toolkit::add), however this method is not available to a running UI. Instead, this method may be used.

Caveat: if an error occurs opening the new window it will not be reported (except via log messages).

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

Close a window or pop-up

pub fn trigger_update(&mut self, handle: UpdateHandle, payload: u64)

Updates all subscribed widgets

All widgets subscribed to the given UpdateHandle, across all windows, will receive an update.

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<'c>(&mut self, content: Cow<'c, str>)

Attempt to set clipboard contents

pub fn adjust_theme<F: FnMut(&mut dyn ThemeApi) -> ThemeAction>(&mut self, f: F)

Adjust the theme

pub fn size_handle<F: FnMut(&mut dyn SizeHandle) -> T, T>(&mut self, f: F) -> T

Access a SizeHandle

impl<'a> Manager<'a>

Public API (around event manager state)

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

Attempts to set a fallback to receive Event::Control

In case a navigation key is pressed (see ControlKey) but no widget has navigation focus, then, if a fallback has been set, that widget will receive the key via Event::Control. (This does not include Event::Activate.)

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

pub fn push_accel_layer(&mut self, alt_bypass: bool)

Add a new accelerator key layer and make it current

This method affects the behaviour of Manager::add_accel_keys by adding a new layer and making this new layer current.

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.

Manager::pop_accel_layer must be called after child widgets have been configured to finish configuration of this new layer and to make the previous layer current.

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, alt_bypass: bool)

Enable alt_bypass for the current layer

This may be called by a child widget during configure, e.g. to enable alt-bypass for the base layer. See also Manager::push_accel_layer.

pub fn pop_accel_layer(&mut self, id: WidgetId)

Finish configuration of an accelerator key layer

This must be called after Manager::push_accel_layer, after configuration of any children using this layer.

The id must be that of the widget which created this layer.

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

Adds an accelerator key for a widget to the current layer

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 Event::Activate.

Note that accelerator keys may be automatically derived from labels: see kas::text::AccelString.

Accelerator keys may be added to the base layer or to a new layer associated with a pop-up (see Manager::push_accel_layer). The top-most active layer gets first priority in matching input, but does not block previous layers.

This should only be called from WidgetConfig::configure.

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

Request character-input focus

If successful, Event::ReceivedCharacter events are sent to this widget when character data is received.

Currently, this method always succeeds.

pub fn request_grab(
    &mut self,
    id: WidgetId,
    source: PressSource,
    coord: Coord,
    mode: GrabMode,
    cursor: Option<CursorIcon>
) -> bool

Request a grab on the given input source

On success, this method returns true and corresponding mouse/touch events will be forwarded to widget id. The grab terminates automatically when the press is released. Returns false when the grab-request fails.

Each grab can optionally visually depress one widget, and initially depresses the widget owning the grab (the id passed here). Call Manager::set_grab_depress to update the grab's depress target. This is cleared automatically when the grab ends.

Behaviour depends on the mode:

• GrabMode::Grab: simple / low-level interpretation of input which delivers Event::PressMove and Event::PressEnd events. Multiple event sources may be grabbed simultaneously.
• All other GrabMode values: generates Event::Pan events. Requesting additional grabs on the same widget from the same source (i.e. multiple touches) allows generation of rotation and scale factors (depending on the GrabMode). Any previously existing Pan grabs by this widgets are replaced.

Since these events are requested, the widget should consume them even if not required, although in practice this only affects parents intercepting Response::Unhandled events.

This method normally succeeds, but fails when multiple widgets attempt a grab the same press source simultaneously (only the first grab is successful).

This method automatically cancels any active character grab on other widgets and updates keyboard navigation focus.

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

Set a grab's depress target

When a grab on mouse or touch input is in effect (Manager::request_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).

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)

Set the keyboard navigation focus directly

WidgetConfig::key_nav should return true for the given widget, otherwise navigation behaviour may not be correct.

pub fn next_nav_focus(
    &mut self,
    widget: &dyn WidgetConfig,
    reverse: bool
) -> bool

Advance the keyboard navigation focus

If some widget currently has nav focus, this will give focus to the next (or previous) widget under widget where WidgetConfig::key_nav returns true; otherwise this will give focus to the first (or last) such widget.

This method returns true when the navigation focus has been updated, otherwise leaves the focus unchanged. The caller may (optionally) choose to call Manager::clear_nav_focus when this method returns false.

Trait Implementations

impl<'a> AddAssign<TkAction> for Manager<'a>

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

Performs the += operation.