Struct kas::event::Manager

pub struct Manager<'a> { /* fields omitted */ }

Manager of event-handling and toolkit actions

A Manager is in fact a handle around ManagerState and [ShellWindow] 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 shells. The latter is hidden from documentation unless the internal_doc feature is enabled.

Implementations

impl<'a> Manager<'a>

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

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 and shell functionality)

pub fn modifiers(&self) -> ModifiersState

Get the current modifier state

pub fn config(&self) -> impl Deref<Target = Config>

Access event-handling configuration

pub fn config_enable_mouse_pan(&self) -> 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 scale_factor(&self) -> f32

Access the screen’s scale factor

pub fn update_on_timer(&mut self, delay: Duration, w_id: WidgetId, payload: u64)

Schedule an update

Widgets requiring animation should schedule an update; as a result, the widget will receive Event::TimerUpdate (with this payload) at approximately time = now + delay.

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.

If multiple updates with the same w_id and payload are requested, these are merged (using the earliest time). Updates with differing w_id or payload are not merged (since presumably they have different purposes).

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 update_shared_data(
    &mut self,
    handle: UpdateHandle,
    data: Rc<dyn Updatable + 'static>
)

Subscribe shaded data to an update handle

Updatable::update_self will be called when the update handle is triggered, and if this method returns another update handle, then all subscribers to that handle are updated in turn.

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.

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 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) -> Option<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.

Returns None if window creation is not currently available (but note that Some result does not guarantee the operation succeeded).

pub fn add_window(
    &mut self,
    widget: Box<dyn Window<Msg = VoidMsg> + 'static, Global>
) -> 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(&mut self, content: String)

Attempt to set clipboard contents

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

Adjust the theme

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

Access a SizeHandle

pub fn draw_shared<F, T>(&mut self, f: F) -> T where
    F: FnMut(&mut dyn DrawShared) -> T, 

Access a DrawShared

This can be accessed through Self::size_handle; this method is merely a shortcut.

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::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. (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 scroll-region widgets 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 crate::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) -> 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 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 update_grab_cursor(&mut self, id: WidgetId, icon: CursorIcon)

Update the mouse cursor used during a grab

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

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

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

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, WidgetConfig::key_nav 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 next_nav_focus(
    &mut self,
    widget: &mut (dyn WidgetConfig + 'static),
    reverse: bool,
    key_focus: 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.

Returns true on success, false if there are no navigable widgets or some error occurred.

The target widget 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.

Trait Implementations

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

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

Performs the |= operation.