Skip to main content

Widget

agg_gui::widget

Trait Widget 

Source 
pub trait Widget {

Show 31 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 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 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 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 take_raise_request(&mut self) -> bool { ... }
    fn needs_paint(&self) -> bool { ... }
    fn next_paint_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 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 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 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 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_paint(&self) -> bool

Return true if this widget, or any visible descendant, has state that requires a repaint (hover change, tween in flight, etc.).

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

Source

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

Return the earliest wall-clock instant at which this widget (or any visible descendant) wants the next paint. 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_paint]: hidden subtrees return None regardless of what the widget would ask for if shown.

Implementors§