Skip to main content

Widget

agg_gui::widget

Trait Widget 

Source 
pub trait Widget {

Show 41 methods    // Required methods
    fn bounds(&self) -> Rect;
    fn set_bounds(&mut self, bounds: Rect);
    fn children(&self) -> &[Box<dyn Widget>];
    fn children_mut(&mut self) -> &mut Vec<Box<dyn Widget>>;
    fn layout(&mut self, available: Size) -> Size;
    fn paint(&mut self, ctx: &mut dyn DrawCtx);
    fn on_event(&mut self, event: &Event) -> EventResult;

    // Provided methods
    fn hit_test(&self, local_pos: Point) -> bool { ... }
    fn claims_pointer_exclusively(&self, _local_pos: Point) -> bool { ... }
    fn hit_test_global_overlay(&self, _local_pos: Point) -> bool { ... }
    fn has_active_modal(&self) -> bool { ... }
    fn on_unconsumed_key(
        &mut self,
        _key: &Key,
        _modifiers: Modifiers,
    ) -> EventResult { ... }
    fn is_focusable(&self) -> bool { ... }
    fn type_name(&self) -> &'static str { ... }
    fn id(&self) -> Option<&str> { ... }
    fn is_visible(&self) -> bool { ... }
    fn properties(&self) -> Vec<(&'static str, String)> { ... }
    fn has_backbuffer(&self) -> bool { ... }
    fn compositing_layer(&mut self) -> Option<CompositingLayer> { ... }
    fn backbuffer_spec(&mut self) -> BackbufferSpec { ... }
    fn backbuffer_state_mut(&mut self) -> Option<&mut BackbufferState> { ... }
    fn mark_dirty(&mut self) { ... }
    fn backbuffer_cache_mut(&mut self) -> Option<&mut BackbufferCache> { ... }
    fn backbuffer_mode(&self) -> BackbufferMode { ... }
    fn contributes_children_to_inspector(&self) -> bool { ... }
    fn show_in_inspector(&self) -> bool { ... }
    fn lcd_preference(&self) -> Option<bool> { ... }
    fn paint_overlay(&mut self, _ctx: &mut dyn DrawCtx) { ... }
    fn finish_paint(&mut self, _ctx: &mut dyn DrawCtx) { ... }
    fn paint_global_overlay(&mut self, _ctx: &mut dyn DrawCtx) { ... }
    fn clip_children_rect(&self) -> Option<(f64, f64, f64, f64)> { ... }
    fn margin(&self) -> Insets { ... }
    fn h_anchor(&self) -> HAnchor { ... }
    fn v_anchor(&self) -> VAnchor { ... }
    fn min_size(&self) -> Size { ... }
    fn max_size(&self) -> Size { ... }
    fn enforce_integer_bounds(&self) -> bool { ... }
    fn measure_min_height(&self, _available_w: f64) -> f64 { ... }
    fn take_raise_request(&mut self) -> bool { ... }
    fn needs_draw(&self) -> bool { ... }
    fn next_draw_deadline(&self) -> Option<Instant> { ... }

}
Expand description

Every visible element in the UI is a widget.

Implementors handle their own painting and event handling. The framework takes care of tree traversal, coordinate translation, and focus management.

Required Methods§

Source

fn bounds(&self) -> Rect

Bounding rectangle in parent-local Y-up coordinates.

Source

fn set_bounds(&mut self, bounds: Rect)

Set the bounding rectangle. Called by the parent during layout.

Source

fn children(&self) -> &[Box<dyn Widget>]

Immutable access to child widgets.

Source

fn children_mut(&mut self) -> &mut Vec<Box<dyn Widget>>

Mutable access to child widgets (required for event dispatch + layout).

Source

fn layout(&mut self, available: Size) -> Size

Compute desired size given available space, and update internal layout.

The parent passes the space it can offer; the widget returns the size it actually wants to occupy. The parent uses the returned size to set this widget’s bounds before calling layout on the next sibling.

Source

fn paint(&mut self, ctx: &mut dyn DrawCtx)

Paint this widget’s own content into ctx.

The framework has already translated ctx so that (0, 0) is this widget’s bottom-left corner. Do not paint children here — the framework recurses into them automatically after paint returns.

ctx is a &mut dyn DrawCtx; the concrete type is either a software GfxCtx (back-buffer path) or a GlGfxCtx (hardware GL path).

Source

fn on_event(&mut self, event: &Event) -> EventResult

Handle an event. The event’s positions are already in local Y-up coordinates. Return EventResult::Consumed to stop bubbling.

Provided Methods§

Source

fn hit_test(&self, local_pos: Point) -> bool

Return true if local_pos (in this widget’s local coordinates) falls inside this widget’s interactive area. Default: axis-aligned rect test.

Source

fn claims_pointer_exclusively(&self, _local_pos: Point) -> bool

When true, hit_test_subtree stops recursing into this widget’s children and returns this widget as the hit target. Used for floating overlays (e.g. a scrollbar painted above its content) that must claim the pointer before children that happen to share the same pixels. Default: false.

Source

fn hit_test_global_overlay(&self, _local_pos: Point) -> bool

Return true when local_pos hits an app-level overlay owned by this widget. Unlike normal hit testing, ancestors may be missed because the overlay is painted outside their bounds.

Source

fn has_active_modal(&self) -> bool

Whether this widget currently owns an app-modal interaction layer.

When true anywhere in the tree, App routes pointer and key events to that modal subtree before normal hit testing so content underneath the modal backdrop cannot be interacted with.

Source

fn on_unconsumed_key( &mut self, _key: &Key, _modifiers: Modifiers, ) -> EventResult

Handle a key that was not consumed by the focused widget path.

This is used for window/menu accelerators: focused controls get first chance at the key, then visible widgets in paint order may claim it.

Source

fn is_focusable(&self) -> bool

Whether this widget can receive keyboard focus. Default: false.

Source

fn type_name(&self) -> &'static str

A static name for this widget type, used by the inspector. Default: “Widget”.

Source

fn id(&self) -> Option<&str>

Optional human-readable identifier for this widget instance.

Distinct from [type_name] (which is per-type and constant): id lets external code look up a specific instance — used today by the demo’s z-order persistence to match a saved title against a live Window in the canvas Stack. Default implementation returns None; widgets that want to be identifiable (e.g. Window returning its title) override.

Source

fn is_visible(&self) -> bool

Return false to suppress painting this widget and all its children. The widget’s own paint() will not be called. Default: true.

Source

fn properties(&self) -> Vec<(&'static str, String)>

Return type-specific properties for the inspector properties pane.

Each entry is (name, display_value). The default returns an empty list; widgets override this to expose their state to the inspector.

Source

fn has_backbuffer(&self) -> bool

Whether this widget renders into its own offscreen buffer before compositing into the parent.

When true, paint_subtree wraps the widget (and all its descendants) in ctx.push_layer / ctx.pop_layer. The widget and its children draw into a fresh transparent framebuffer; when complete, the buffer is SrcOver-composited back into the parent render target. This enables per-widget alpha compositing, caching, and isolation.

Default: false (pass-through rendering).

Source

fn compositing_layer(&mut self) -> Option<CompositingLayer>

Request that this widget subtree be painted into a transient transparent compositing layer before being blended into its parent.

Renderers that do not implement real layers ignore this hook. The method is mutable so widgets can advance visibility tweens at the point where the traversal knows the layer will be painted.

Source

fn backbuffer_spec(&mut self) -> BackbufferSpec

Unified widget-owned backbuffer request.

Source

fn backbuffer_state_mut(&mut self) -> Option<&mut BackbufferState>

Mutable retained backbuffer state for widgets that request a BackbufferSpec other than BackbufferKind::None.

Source

fn mark_dirty(&mut self)

Mark this widget’s own retained surface dirty, if it owns one.

Source

fn backbuffer_cache_mut(&mut self) -> Option<&mut BackbufferCache>

Opt into per-widget CPU bitmap caching with a dirty flag.

Widgets that return Some(&mut cache) get their paint + children cached as a Vec<u8> of RGBA8 pixels. paint_subtree re-rasterises via AGG only when cache.dirty is true; otherwise it blits the existing bitmap. GL backends key their texture cache on the Arc’s pointer identity so the uploaded GPU texture is also reused across frames.

The widget is responsible for calling cache.invalidate() (or setting cache.dirty = true) from any mutation that could change the rendered output — text/color setters, focus/hover state changes, layout size changes, etc. The framework clears the flag after a successful re-raster.

Default: None (no caching — paint every frame directly).

Source

fn backbuffer_mode(&self) -> BackbufferMode

Storage format for this widget’s backbuffer. Ignored unless [backbuffer_cache_mut] returns Some. Default BackbufferMode::Rgba — correct for any widget. Opt into BackbufferMode::LcdCoverage only when the widget paints opaque content covering its full bounds.

Source

fn contributes_children_to_inspector(&self) -> bool

Whether the inspector should recurse into this widget’s children.

Returns false for widgets that are part of the inspector infrastructure (e.g. the inspector’s own TreeView) to prevent the inspector from showing itself recursively, which would grow the node list every frame.

The widget itself is still included in the inspector snapshot — only its subtree is suppressed.

Source

fn show_in_inspector(&self) -> bool

Return false to hide this widget (and its subtree) from the inspector node snapshot entirely. Intended for zero-size utility widgets such as layout-time watchers / tickers / invisible composers — they bloat the inspector tree without providing user-relevant information and, at scale, can make the inspector’s per-frame tree rebuild expensive.

Source

fn lcd_preference(&self) -> Option<bool>

Per-widget LCD subpixel preference for backbuffered text rendering.

  • Some(true) — always raster text with LCD subpixel.
  • Some(false) — always use grayscale AA.
  • None — defer to the global font_settings::lcd_enabled().

Only widgets that raster text into an offscreen backbuffer act on this flag (today: Label). Defaulting to None means every such widget follows the global toggle unless the instance explicitly opts in or out.

Source

fn paint_overlay(&mut self, _ctx: &mut dyn DrawCtx)

Paint decorations that must appear on top of all children.

Called by paint_subtree after all children have been painted. The default implementation is a no-op; override in widgets that need to draw overlays (e.g. resize handles, drag previews) that must not be occluded by child content.

Source

fn finish_paint(&mut self, _ctx: &mut dyn DrawCtx)

Called after paint, child painting, and optional overlay painting.

Most widgets do not need this. It exists for widgets that intentionally open a backend compositing scope in paint and must close it after all descendants have rendered into that scope.

Source

fn paint_global_overlay(&mut self, _ctx: &mut dyn DrawCtx)

Paint app-level overlays after the entire widget tree has been painted.

The traversal preserves this widget’s local transform but skips ancestor clips and retained parent redraw requirements. Use this for portal-style UI that draws outside normal bounds while still participating in the widget tree’s Z order.

Source

fn clip_children_rect(&self) -> Option<(f64, f64, f64, f64)>

Return a clip rectangle (in local coordinates) that constrains all child painting. paint_subtree applies this clip before recursing into children, then restores the previous clip state afterward. The clip does not affect paint_overlay, which runs after the clip is removed.

The default clips children to this widget’s own bounds, preventing overflow. Override to return a narrower rect (e.g. Window clips to the content area below the title bar, or an empty rect when collapsed).

Source

fn margin(&self) -> Insets

Outer margin around this widget in logical units.

The parent layout reads this to compute spacing and position. Default: Insets::ZERO.

Source

fn h_anchor(&self) -> HAnchor

Horizontal anchor: how this widget sizes/positions itself horizontally within the slot the parent assigns. Default: HAnchor::FIT (take natural content width).

Source

fn v_anchor(&self) -> VAnchor

Vertical anchor: how this widget sizes/positions itself vertically within the slot the parent assigns. Default: VAnchor::FIT (take natural content height).

Source

fn min_size(&self) -> Size

Minimum size constraint (logical units).

The parent will never assign a slot smaller than this. Default: Size::ZERO (no minimum).

Source

fn max_size(&self) -> Size

Maximum size constraint (logical units).

The parent will never assign a slot larger than this. Default: Size::MAX (no maximum).

Source

fn enforce_integer_bounds(&self) -> bool

Whether paint_subtree should snap this widget’s incoming translation to the physical pixel grid.

Defaults to the process-wide pixel_bounds::default_enforce_integer_bounds flag so the common case — crisp UI text + strokes — works without ceremony. Widgets with a [WidgetBase] should delegate to self.base().enforce_integer_bounds so per-instance overrides take effect; widgets that genuinely want sub-pixel positioning (smooth scroll markers, zoomed canvases) override to return false.

Mirrors MatterCAD’s GuiWidget.EnforceIntegerBounds accessor.

Source

fn measure_min_height(&self, _available_w: f64) -> f64

Report the minimum height this widget needs to fully render its content when given the supplied available_w for width.

Used by parents whose layout strategy depends on a true content-required height that’s independent of the slot they might hand the widget — most importantly by Window::with_tight_content_fit(true) to enforce “no clipping, no whitespace” on the height axis even when the content tree contains a flex-fill widget that would otherwise return available.height from layout.

Default returns min_size().height — accurate for widgets whose minimum doesn’t depend on width. Width-sensitive widgets (wrapped text containers like TextArea, recursive containers like FlexColumn) override and compute properly.

Source

fn take_raise_request(&mut self) -> bool

Container widgets (notably crate::widgets::Stack) call this on each child at the start of layout(). A widget that returns true is moved to the END of its parent’s child list — painted last, i.e. raised to the top of the z-order. take_ semantics: the call is also expected to clear the request so the child doesn’t keep getting raised every frame.

Default: no raise ever requested. Window overrides to fire on the false→true visibility transition (see its with_visible_cell), so toggling a demo checkbox on in the sidebar automatically pops that window to the front.

Source

fn needs_draw(&self) -> bool

Return true if this widget, or any visible descendant, has an ongoing draw need that should keep the host drawing.

The default walks visible children. Widgets with their own pending state OR that state with the default walk — see WidgetBase helpers.

Source

fn next_draw_deadline(&self) -> Option<Instant>

Return the earliest wall-clock instant at which this widget (or any visible descendant) wants the next draw. None = no scheduled wake. The host loop turns a Some(t) into ControlFlow::WaitUntil(t) so e.g. a cursor blink fires without continuous polling.

Same visibility contract as [needs_draw]: hidden subtrees return None regardless of what the widget would ask for if shown.

Implementors§