Trait druid::Widget

pub trait Widget<T> {
    // Required methods
    fn event(
        &mut self,
        ctx: &mut EventCtx<'_, '_>,
        event: &Event,
        data: &mut T,
        env: &Env
    );
    fn lifecycle(
        &mut self,
        ctx: &mut LifeCycleCtx<'_, '_>,
        event: &LifeCycle,
        data: &T,
        env: &Env
    );
    fn update(
        &mut self,
        ctx: &mut UpdateCtx<'_, '_>,
        old_data: &T,
        data: &T,
        env: &Env
    );
    fn layout(
        &mut self,
        ctx: &mut LayoutCtx<'_, '_>,
        bc: &BoxConstraints,
        data: &T,
        env: &Env
    ) -> Size;
    fn paint(&mut self, ctx: &mut PaintCtx<'_, '_, '_>, data: &T, env: &Env);

    // Provided method
    fn compute_max_intrinsic(
        &mut self,
        axis: Axis,
        ctx: &mut LayoutCtx<'_, '_>,
        bc: &BoxConstraints,
        data: &T,
        env: &Env
    ) -> f64 { ... }
}

The trait implemented by all widgets.

All appearance and behavior for a widget is encapsulated in an object that implements this trait.

The trait is parametrized by a type (T) for associated data. All trait methods are provided with access to this data, and in the case of event the reference is mutable, so that events can directly update the data.

Whenever the application data changes, the framework traverses the widget hierarchy with an update method. The framework needs to know whether the data has actually changed or not, which is why T has a Data bound.

All the trait methods are provided with a corresponding context. The widget can request things and cause actions by calling methods on that context.

In addition, all trait methods are provided with an environment (Env).

Container widgets will generally not call Widget methods directly on their child widgets, but rather will own their widget wrapped in a WidgetPod, and call the corresponding method on that. The WidgetPod contains state and logic for these traversals. On the other hand, particularly light-weight containers might contain their child Widget directly (when no layout or event flow logic is needed), and in those cases will call these methods.

As a general pattern, container widgets will call the corresponding WidgetPod method on all their children. The WidgetPod applies logic to determine whether to recurse, as needed.

Required Methods

fn event( &mut self, ctx: &mut EventCtx<'_, '_>, event: &Event, data: &mut T, env: &Env )

Handle an event.

A number of different events (in the Event enum) are handled in this method call. A widget can handle these events in a number of ways: requesting things from the EventCtx, mutating the data, or submitting a Command.

fn lifecycle( &mut self, ctx: &mut LifeCycleCtx<'_, '_>, event: &LifeCycle, data: &T, env: &Env )

Handle a life cycle notification.

This method is called to notify your widget of certain special events, (available in the LifeCycle enum) that are generally related to changes in the widget graph or in the state of your specific widget.

A widget is not expected to mutate the application state in response to these events, but only to update its own internal state as required; if a widget needs to mutate data, it can submit a Command that will be executed at the next opportunity.

fn update(&mut self, ctx: &mut UpdateCtx<'_, '_>, old_data: &T, data: &T, env: &Env)

Update the widget’s appearance in response to a change in the app’s Data or Env.

This method is called whenever the data or environment changes. When the appearance of the widget needs to be updated in response to these changes, you can call request_paint or request_layout on the provided UpdateCtx to schedule calls to paint and layout as required.

The previous value of the data is provided in case the widget wants to compute a fine-grained delta; you should try to only request a new layout or paint pass if it is actually required.

To determine if the Env has changed, you can call env_changed on the provided UpdateCtx; you can then call env_key_changed with any keys that are used in your widget, to see if they have changed; you can then request layout or paint as needed.

fn layout( &mut self, ctx: &mut LayoutCtx<'_, '_>, bc: &BoxConstraints, data: &T, env: &Env ) -> Size

Compute layout.

A leaf widget should determine its size (subject to the provided constraints) and return it.

A container widget will recursively call WidgetPod::layout on its child widgets, providing each of them an appropriate box constraint, compute layout, then call set_origin on each of its children. Finally, it should return the size of the container. The container can recurse in any order, which can be helpful to, for example, compute the size of non-flex widgets first, to determine the amount of space available for the flex widgets.

For efficiency, a container should only invoke layout of a child widget once, though there is nothing enforcing this.

The layout strategy is strongly inspired by Flutter.

fn paint(&mut self, ctx: &mut PaintCtx<'_, '_, '_>, data: &T, env: &Env)

Paint the widget appearance.

The PaintCtx derefs to something that implements the RenderContext trait, which exposes various methods that the widget can use to paint its appearance.

Container widgets can paint a background before recursing to their children, or annotations (for example, scrollbars) by painting afterwards. In addition, they can apply masks and transforms on the render context, which is especially useful for scrolling.

Provided Methods

fn compute_max_intrinsic( &mut self, axis: Axis, ctx: &mut LayoutCtx<'_, '_>, bc: &BoxConstraints, data: &T, env: &Env ) -> f64

Computes max intrinsic/preferred dimension of a widget on the provided axis.

Max intrinsic/preferred dimension is the dimension the widget could take, provided infinite constraint on that axis.

If axis == Axis::Horizontal, widget is being asked to calculate max intrinsic width. If axis == Axis::Vertical, widget is being asked to calculate max intrinsic height.

Box constraints must be honored in intrinsics computation.

AspectRatioBox is an example where constraints are honored. If height is finite, max intrinsic width is height * ratio. Only when height is infinite, child’s max intrinsic width is calculated.

Intrinsic is a could-be value. It’s the value a widget could have given infinite constraints. This does not mean the value returned by layout() would be the same.

This method must return a finite value.

Trait Implementations

impl<T> Widget<T> for Box<dyn Widget<T>>

fn event( &mut self, ctx: &mut EventCtx<'_, '_>, event: &Event, data: &mut T, env: &Env )

Handle an event.

fn lifecycle( &mut self, ctx: &mut LifeCycleCtx<'_, '_>, event: &LifeCycle, data: &T, env: &Env )

Handle a life cycle notification.

fn update(&mut self, ctx: &mut UpdateCtx<'_, '_>, old_data: &T, data: &T, env: &Env)

Update the widget’s appearance in response to a change in the app’s Data or Env.

fn layout( &mut self, ctx: &mut LayoutCtx<'_, '_>, bc: &BoxConstraints, data: &T, env: &Env ) -> Size

Compute layout.

fn paint(&mut self, ctx: &mut PaintCtx<'_, '_, '_>, data: &T, env: &Env)

Paint the widget appearance.

fn compute_max_intrinsic( &mut self, axis: Axis, ctx: &mut LayoutCtx<'_, '_>, bc: &BoxConstraints, data: &T, env: &Env ) -> f64

Computes max intrinsic/preferred dimension of a widget on the provided axis.

Implementations on Foreign Types

impl<T> Widget<T> for Box<dyn Widget<T>>

fn event( &mut self, ctx: &mut EventCtx<'_, '_>, event: &Event, data: &mut T, env: &Env )

fn lifecycle( &mut self, ctx: &mut LifeCycleCtx<'_, '_>, event: &LifeCycle, data: &T, env: &Env )

fn update(&mut self, ctx: &mut UpdateCtx<'_, '_>, old_data: &T, data: &T, env: &Env)

fn layout( &mut self, ctx: &mut LayoutCtx<'_, '_>, bc: &BoxConstraints, data: &T, env: &Env ) -> Size

fn paint(&mut self, ctx: &mut PaintCtx<'_, '_, '_>, data: &T, env: &Env)

fn compute_max_intrinsic( &mut self, axis: Axis, ctx: &mut LayoutCtx<'_, '_>, bc: &BoxConstraints, data: &T, env: &Env ) -> f64

Implementors

impl Widget<(f64, f64)> for RangeSlider

impl Widget<bool> for Checkbox

impl Widget<bool> for Switch

impl Widget<f64> for ProgressBar

impl Widget<f64> for Slider

impl Widget<f64> for Stepper

impl<C: Data, T: ListIter<C>> Widget<T> for List<C>

impl<S, T: Data> Widget<T> for ModularWidget<S, T>

impl<SP: ScopePolicy, W: Widget<SP::State>> Widget<<SP as ScopePolicy>::In> for Scope<SP, W>

impl<T, U, L, W> Widget<T> for LensWrap<T, U, L, W>where T: Data, U: Data, L: Lens<T, U>, W: Widget<U>,

impl<T, W: Widget<T>, C: Controller<T, W>> Widget<T> for ControllerHost<W, C>

impl<T: TextStorage + EditableText> Widget<T> for TextComponent<T>

impl<T: TextStorage + EditableText> Widget<T> for TextBox<T>

impl<T: TextStorage> Widget<T> for RawLabel<T>

impl<T: Data + PartialEq> Widget<T> for Radio<T>

impl<T: Data + Debug> Widget<T> for ValueTextBox<T>

impl<T: Data> Widget<Option<T>> for Maybe<T>

impl<T: Data> Widget<T> for ReplaceChild<T>

impl<T: Data> Widget<T> for Align<T>

impl<T: Data> Widget<T> for AspectRatioBox<T>

impl<T: Data> Widget<T> for Button<T>

impl<T: Data> Widget<T> for Container<T>

impl<T: Data> Widget<T> for Either<T>

impl<T: Data> Widget<T> for Flex<T>

impl<T: Data> Widget<T> for Image

impl<T: Data> Widget<T> for IntrinsicWidth<T>

impl<T: Data> Widget<T> for Label<T>

impl<T: Data> Widget<T> for Painter<T>

impl<T: Data> Widget<T> for SizedBox<T>

impl<T: Data> Widget<T> for Spinner

impl<T: Data> Widget<T> for Split<T>

impl<T: Data> Widget<T> for Svg

Available on crate feature svg only.

impl<T: Data> Widget<T> for ZStack<T>

impl<T: Data, U: Data> Widget<T> for ViewSwitcher<T, U>

impl<T: Data, W: Widget<T>> Widget<T> for Recorder<W>

impl<T: Data, W: Widget<T>> Widget<T> for ClipBox<T, W>

impl<T: Data, W: Widget<T>> Widget<T> for DisabledIf<T, W>

impl<T: Data, W: Widget<T>> Widget<T> for EnvScope<T, W>

impl<T: Data, W: Widget<T>> Widget<T> for IdentityWrapper<W>

impl<T: Data, W: Widget<T>> Widget<T> for Padding<T, W>

impl<T: Data, W: Widget<T>> Widget<T> for Scroll<T, W>

impl<TP: TabsPolicy> Widget<<TP as TabsPolicy>::Input> for Tabs<TP>