Struct masonry::WidgetCtx

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

A context provided inside of WidgetMut.

When you declare a mutable reference type for your widget, methods of this type will have access to a WidgetCtx. If that method mutates the widget in a way that requires a later pass (for instance, if your widget has a set_color method), you will need to signal that change in the pass (eg request_paint).

Implementations

impl WidgetCtx<'_>

pub fn widget_id(&self) -> WidgetId

get the WidgetId of the current widget.

pub fn skip_child(&self, child: &mut WidgetPod<impl Widget>)

Skip iterating over the given child.

Normally, container widgets are supposed to iterate over each of their child widgets in their methods. By default, the framework treats not doing so as a mistake, and panics if debug assertions are on.

This tells the framework that a child was deliberately skipped.

impl WidgetCtx<'_>

pub fn size(&self) -> Size

The layout size.

This is the layout size as ultimately determined by the parent container, on the previous layout pass.

Generally it will be the same as the size returned by the child widget’s layout method.

pub fn window_origin(&self) -> Point

The origin of the widget in window coordinates, relative to the top left corner of the content area.

pub fn to_window(&self, widget_point: Point) -> Point

Convert a point from the widget’s coordinate space to the window’s.

The returned point is relative to the content area; it excludes window chrome.

pub fn is_hot(&self) -> bool

The “hot” (aka hover) status of a widget.

A widget is “hot” when the mouse is hovered over it. Widgets will often change their appearance as a visual indication that they will respond to mouse interaction.

The hot status is computed from the widget’s layout rect. In a container hierarchy, all widgets with layout rects containing the mouse position have hot status.

Discussion: there is currently some confusion about whether a widget can be considered hot when some other widget is active (for example, when clicking to one widget and dragging to the next). The documentation should clearly state the resolution.

pub fn is_active(&self) -> bool

The active status of a widget.

Active status generally corresponds to a mouse button down. Widgets with behavior similar to a button will call set_active on mouse down and then up.

When a widget is active, it gets mouse events even when the mouse is dragged away.

pub fn is_focused(&self) -> bool

The focus status of a widget.

Returns true if this specific widget is focused. To check if any descendants are focused use has_focus.

Focus means that the widget receives keyboard events.

A widget can request focus using the request_focus method. It’s also possible to register for automatic focus via register_for_focus.

If a widget gains or loses focus it will get a LifeCycle::FocusChanged event.

Only one widget at a time is focused. However due to the way events are routed, all ancestors of that widget will also receive keyboard events.

pub fn has_focus(&self) -> bool

The (tree) focus status of a widget.

Returns true if either this specific widget or any one of its descendants is focused. To check if only this specific widget is focused use is_focused.

pub fn is_disabled(&self) -> bool

The disabled state of a widget.

Returns true if this widget or any of its ancestors is explicitly disabled. To make this widget explicitly disabled use set_disabled.

Disabled means that this widget should not change the state of the application. What that means is not entirely clear but in any it should not change its data. Therefore others can use this as a safety mechanism to prevent the application from entering an illegal state. For an example the decrease button of a counter of type usize should be disabled if the value is 0.

pub fn is_stashed(&self) -> bool

Check is widget is stashed.

Note: Stashed widgets are a WIP feature

impl<'a> WidgetCtx<'a>

pub fn get_mut<'c, Child: Widget>( &'c mut self, child: &'c mut WidgetPod<Child> ) -> WidgetMut<'c, Child>

Return a WidgetMut to a child widget.

impl WidgetCtx<'_>

pub fn request_paint(&mut self)

Request a paint pass.

pub fn request_layout(&mut self)

Request a layout pass.

A Widget’s layout method is always called when the widget tree changes, or the window is resized.

If your widget would like to have layout called at any other time, (such as if it would like to change the layout of children in response to some event) it must call this method.

pub fn request_accessibility_update(&mut self)

pub fn request_anim_frame(&mut self)

Request an animation frame.

pub fn children_changed(&mut self)

Indicate that your children have changed.

Widgets must call this method after adding a new child or removing a child.

pub fn set_disabled(&mut self, disabled: bool)

Set the disabled state for this widget.

Setting this to false does not mean a widget is not still disabled; for instance it may still be disabled by an ancestor. See is_disabled for more information.

Calling this method during LifeCycle::DisabledChanged has no effect.

pub fn set_stashed(&mut self, child: &mut WidgetPod<impl Widget>, stashed: bool)

Mark child widget as stashed.

Note: Stashed widgets are a WIP feature

pub fn invalidate_text_input(&mut self, event: ImeChangeSignal)

Indicate that text input state has changed.

A widget that accepts text input should call this anytime input state (such as the text or the selection) changes as a result of a non text-input event.

impl WidgetCtx<'_>

pub fn submit_action(&mut self, action: Action)

Submit an Action.

Note: Actions are still a WIP feature.

pub fn run_in_background( &mut self, _background_task: impl FnOnce(WorkerCtx<'_>) + Send + 'static )

Run the provided function in the background.

The function takes a [WorkerCtx] which it can use to communicate with the main thread.

pub fn compute_in_background<T: Any + Send>( &mut self, _background_task: impl FnOnce(WorkerCtx<'_>) -> T + Send + 'static ) -> PromiseToken<T>

Run the provided function in the background, and send its result once it’s done.

The function takes a [WorkerCtx] which it can use to communicate with the main thread.

Once the function returns, an Event::PromiseResult is emitted with the return value.

pub fn request_timer(&mut self, _deadline: Duration) -> TimerToken

Request a timer event.

The return value is a token, which can be used to associate the request with the event.