Struct SizeCx 

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

Size and scaling interface

This context provides scaled sizing information from the theme.

Most methods get or calculate the size of some feature. These same features may be drawn through DrawCx.

Implementations

impl<'a> SizeCx<'a>

pub fn scale_factor(&self) -> f32

Get the scale factor

“Traditional” PC screens have a scale factor of 1; high-DPI screens may have a factor of 2 or higher. This may be fractional and may be adjusted to suit the device type (e.g. a phone or desktop monitor) as well as the user’s preference.

One could use this value to calculate physical size, but be warned that the result may be quite inaccurate on anything other than a desktop monitor: 25.4 mm = 1 inch = (96 * scale_factor) pixels

To calculate screen pixel sizes from virtual pixel sizes:

use kas_core::cast::*;
let size: i32 = (100.0 * scale_factor).cast_ceil();

This value may change during a program’s execution (e.g. when a window is moved to a different monitor); in this case all widgets will be resized via crate::Layout::size_rules.

pub fn logical(&self, width: f32, height: f32) -> LogicalBuilder

Build SizeRules from the input size in logical pixels

pub fn font(&self, class: TextClass) -> FontSelector

Get the configured font selector for class

pub fn dpem(&self, class: TextClass) -> f32

Get the default font size for class

Units are physical pixels per font Em.

The Em is a unit of typography (variously defined as the point-size of the font, the height of the font or the width of an upper-case M).

This method returns the size of 1 Em in physical pixels, derived from the font size in use by the theme and the screen’s scale factor.

pub fn wrapped_line_len(&self, class: TextClass, dpem: f32) -> (i32, i32)

Get the (min, ideal) line length for text which wraps

pub fn min_element_size(&self) -> i32

The smallest reasonable size for a visible (non-frame) component

This is used as a suggestion by some heuristics.

pub fn min_scroll_size( &self, axis: impl Directional, class: Option<TextClass>, ) -> i32

The minimum size of a scrollable area

pub fn grip_len(&self) -> i32

The length of the grip (draggable handle) on a scroll bar or slider

This is the length in line with the control. The size on the opposite axis is assumed to be equal to the feature size as reported by Self::feature.

pub fn scroll_bar_width(&self) -> i32

The width of a vertical scroll bar

This value is also available through Self::feature.

pub fn margins(&self, style: MarginStyle) -> Margins

Get margin size

pub fn inner_margins(&self) -> Margins

Get margins for MarginStyle::Inner

pub fn tiny_margins(&self) -> Margins

Get margins for MarginStyle::Tiny

pub fn small_margins(&self) -> Margins

Get margins for MarginStyle::Small

pub fn large_margins(&self) -> Margins

Get margins for MarginStyle::Large

pub fn text_margins(&self) -> Margins

Get margins for MarginStyle::Text

pub fn feature(&self, feature: Feature, axis: impl Directional) -> SizeRules

Size rules for a feature

pub fn frame(&self, style: FrameStyle, axis: impl Directional) -> FrameRules

Size of a frame around another element

pub fn align_feature( &self, feature: Feature, rect: Rect, align: AlignPair, ) -> Rect

Align a feature’s rect

In case the input rect is larger than desired on either axis, it is reduced in size and offset within the original rect as is preferred.

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 SizeCx<'a>

type Target = EventState

The resulting type after dereferencing.

fn deref(&self) -> &EventState

Dereferences the value.

impl<'a> DerefMut for SizeCx<'a>

fn deref_mut(&mut self) -> &mut EventState

Mutably dereferences the value.