Struct druid::UpdateCtx

pub struct UpdateCtx<'a, 'b> { /* private fields */ }

A mutable context provided to data update methods of widgets.

Widgets should call request_paint whenever a data change causes a change in the widget’s appearance, to schedule a repaint.

Implementations

impl UpdateCtx<'_, '_>

pub fn widget_id(&self) -> WidgetId

get the WidgetId of the current widget.

pub fn window(&self) -> &WindowHandle

Returns a reference to the current WindowHandle.

pub fn window_id(&self) -> WindowId

Get the WindowId of the current window.

pub fn text(&mut self) -> &mut PietText

Get an object which can create text layouts.

pub fn scale(&self) -> Scale

The current window’s Scale.

The returned Scale is a copy and thus its information will be stale after the platform changes the window’s scale. This means you can only rely on it until the next Event::WindowScale event happens.

impl UpdateCtx<'_, '_>

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 to_screen(&self, widget_point: Point) -> Point

Convert a point from the widget’s coordinate space to the screen’s. See the Screen module

pub fn is_hot(&self) -> bool

Query the “hot” state of the widget.

See WidgetPod::is_hot for additional information.

pub fn is_active(&self) -> bool

Query the “active” state of the widget.

See WidgetPod::is_active for additional information.

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.

impl UpdateCtx<'_, '_>

pub fn set_cursor(&mut self, cursor: &Cursor)

Set the cursor icon.

This setting will be retained until clear_cursor is called, but it will only take effect when this widget is either hot or active. If a child widget also sets a cursor, the child widget’s cursor will take precedence. (If that isn’t what you want, use override_cursor instead.)

pub fn override_cursor(&mut self, cursor: &Cursor)

Override the cursor icon.

This setting will be retained until clear_cursor is called, but it will only take effect when this widget is either hot or active. This will override the cursor preferences of a child widget. (If that isn’t what you want, use set_cursor instead.)

pub fn clear_cursor(&mut self)

Clear the cursor icon.

This undoes the effect of set_cursor and override_cursor.

impl UpdateCtx<'_, '_>

pub fn view_context_changed(&mut self)

Indicate that your ViewContext has changed.

This event is sent after layout is done and before paint is called. Note that you can still receive this event even if there was no prior call to layout.

Widgets must call this method after changing the clip region of their children. Changes to the other parts of ViewContext (cursor position and global origin) are tracked internally.

impl UpdateCtx<'_, '_>

pub fn request_paint(&mut self)

Request a paint pass. This is equivalent to calling request_paint_rect for the widget’s paint_rect.

Examples found in repository

examples/multiwin.rs (line 104)

    fn update(&mut self, ctx: &mut UpdateCtx, old_data: &State, data: &State, env: &Env) {
        if old_data.glow_hot != data.glow_hot {
            ctx.request_paint();
        }
        self.inner.update(ctx, old_data, data, env);
    }

examples/game_of_life.rs (line 278)

    fn update(&mut self, ctx: &mut UpdateCtx, old_data: &AppData, data: &AppData, _env: &Env) {
        if (data.updates_per_second - old_data.updates_per_second).abs() > 0.001 {
            let deadline = Duration::from_millis(data.iter_interval())
                .checked_sub(Instant::now().duration_since(self.last_update))
                .unwrap_or_else(|| Duration::from_secs(0));
            self.timer_id = ctx.request_timer(deadline);
        }
        if data.grid != old_data.grid {
            ctx.request_paint();
        }
    }

pub fn request_paint_rect(&mut self, rect: Rect)

Request a paint pass for redrawing a rectangle, which is given relative to our layout rectangle.

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.

Examples found in repository

examples/text.rs (line 73)

    fn update(
        &mut self,
        child: &mut RawLabel<AppState>,
        ctx: &mut UpdateCtx,
        old_data: &AppState,
        data: &AppState,
        env: &Env,
    ) {
        if old_data.line_break_mode != data.line_break_mode {
            child.set_line_break_mode(data.line_break_mode);
            ctx.request_layout();
        }
        if old_data.alignment != data.alignment {
            child.set_text_alignment(data.alignment);
            ctx.request_layout();
        }
        child.update(ctx, old_data, data, env);
    }

pub fn request_anim_frame(&mut self)

Request an AnimFrame event.

Receiving AnimFrame does not inherently mean a paint invocation will follow. If you want something actually painted you need to explicitly call request_paint or request_paint_rect when handling the AnimFrame event.

Note that not requesting paint when handling the AnimFrame event and then recursively requesting another AnimFrame can lead to rapid event fire, which is probably not what you want and would most likely be wasted compute cycles.

pub fn children_changed(&mut self)

Indicate that your children have changed.

Widgets must call this method after adding a new child, removing a child or changing which children are hidden (see should_propagate_to_hidden).

Examples found in repository

examples/flex.rs (line 128)

    fn update(&mut self, ctx: &mut UpdateCtx, old_data: &AppState, data: &AppState, env: &Env) {
        if !old_data.params.same(&data.params) {
            self.rebuild_inner(data);
            ctx.children_changed();
        } else {
            self.inner.update(ctx, old_data, data, env);
        }
    }

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 invalidate_text_input(&mut self, event: ImeInvalidation)

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.

pub fn new_sub_window<W: Widget<U> + 'static, U: Data>( &mut self, window_config: WindowConfig, widget: W, data: U, env: Env ) -> WindowId

Create a new sub-window.

The sub-window will have its app data synchronised with caller’s nearest ancestor WidgetPod. ‘U’ must be the type of the nearest surrounding WidgetPod. The ‘data’ argument should be the current value of data for that widget.

pub fn scroll_to_view(&mut self)

Scrolls this widget into view.

If this widget is only partially visible or not visible at all because of Scrolls it is wrapped in, they will do the minimum amount of scrolling necessary to bring this widget fully into view.

If the widget is hidden, this method has no effect.

This functionality is achieved by sending a SCROLL_TO_VIEW notification.

impl UpdateCtx<'_, '_>

pub fn submit_command(&mut self, cmd: impl Into<Command>)

Submit a Command to be run after this event is handled.

Commands are run in the order they are submitted; all commands submitted during the handling of an event are executed before the update method is called; events submitted during update are handled after painting.

Target::Auto commands will be sent to the window containing the widget.

pub fn get_external_handle(&self) -> ExtEventSink

Returns an ExtEventSink that can be moved between threads, and can be used to submit commands back to the application.

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.

Examples found in repository

examples/game_of_life.rs (line 275)

    fn update(&mut self, ctx: &mut UpdateCtx, old_data: &AppData, data: &AppData, _env: &Env) {
        if (data.updates_per_second - old_data.updates_per_second).abs() > 0.001 {
            let deadline = Duration::from_millis(data.iter_interval())
                .checked_sub(Instant::now().duration_since(self.last_update))
                .unwrap_or_else(|| Duration::from_secs(0));
            self.timer_id = ctx.request_timer(deadline);
        }
        if data.grid != old_data.grid {
            ctx.request_paint();
        }
    }

impl UpdateCtx<'_, '_>

pub fn has_requested_update(&mut self) -> bool

Returns true if this widget or a descendent as explicitly requested an update call.

This should only be needed in advanced cases; see EventCtx::request_update for more information.

pub fn env_changed(&self) -> bool

Returns true if the current Env has changed since the previous update call.

pub fn env_key_changed<T>(&self, key: &impl KeyLike<T>) -> bool

Returns true if the given key has changed since the last update call.

The argument can be anything that is resolveable from the Env, such as a Key or a KeyOrValue.

pub fn scroll_area_to_view(&mut self, area: Rect)

Scrolls the area into view.

If the area is only partially visible or not visible at all because of Scrolls this widget is wrapped in, they will do the minimum amount of scrolling necessary to bring the area fully into view.

If the widget is hidden, this method has no effect.