Struct Avatar 

pub struct Avatar { /* private fields */ }

Circular (or rounded-square / square) user-identity widget showing either a photo or hash-tinted initials, with an optional presence dot.

Static and reactive content fields coexist: each knob (name, image, alt, label, presence) has a static constructor or setter and a bind_* counterpart that takes a Signal. When a signal is bound it wins; the static value acts as a fallback. Signal-bound rebuilds fire at BindingLevel::Rebuild so inner children are recreated with fresh values — the canonical pattern for a “logged-out → logged-in” transition.

Implementations

impl Avatar

pub fn with_initials(initials: impl Into<LocalizedString>) -> Self

Create an avatar from an explicit initials string. Uppercases and truncates to at most 2 chars; empty input yields "?".

pub fn with_name(name: impl Into<LocalizedString>) -> Self

Create an avatar from a display name; initials are derived automatically ("Jane Doe" → "JD", "jane.doe@x.com" → "JD", "Cher" → "C", "" → "?"), and the full name is used as the hash seed for the background tint so users with identical initials still get distinct colours.

pub fn with_image(icon: &RasterIcon) -> Self

Create an avatar from a decoded [RasterIcon]. The pixels are centre-cropped to a square and CPU-masked to the configured shape at the first build(). Call .alt(...) to provide a screen-reader name for the image.

pub fn from_raw_image(pixels: Vec<u8>, width: u32, height: u32) -> Self

Create an avatar from raw RGBA pixels (width × height × 4 bytes). Same pixel-layout convention as ImageWidget::from_raw.

pub fn style(self, style: impl AvatarStyle) -> Self

Per-call style override for the avatar chrome.

impl Avatar

pub fn size(self, size: AvatarSize) -> Self

Set the avatar’s discrete size. Default: AvatarSize::Medium (32 dp).

pub fn shape(self, shape: AvatarShape) -> Self

Set the avatar’s clip shape. Default: AvatarShape::Circle.

pub fn fallback_initials(self, initials: impl Into<LocalizedString>) -> Self

Override the initials shown when the image is hidden via image_visible(false) or fails to register. Defaults to the derived initials if with_image was paired with with_name, otherwise "?".

pub fn image_visible(self, visible: impl Into<Prop<bool>>) -> Self

Reactive image visibility. When unbound it’s true. When bound to a Signal<bool> and the value is false, the initials fallback paints in place of the image — same logical bounds, no layout shift.

pub fn background(self, color: impl Into<ColorProp>) -> Self

Override the auto hash-derived background. Accepts a [Color], a role, or a Signal<Color>.

pub fn foreground(self, color: impl Into<ColorProp>) -> Self

Override the auto-contrast text colour for the initials. Auto (unset) picks white over dark backgrounds and near-black over light ones, computed at paint time from the resolved bg’s luminance.

pub fn seed(self, seed: impl Into<String>) -> Self

Override the seed string used to pick a hash-derived background from the theme’s chart palette. Defaults to the resolved name (when constructed via with_name) or the initials.

pub fn border(self, width: f32) -> Self

Outer ring thickness. A non-zero value enables the ring (drawn in BorderRole::Default unless Self::border_color overrides it). 0.0 disables the ring.

pub fn border_color(self, color: impl Into<ColorProp>) -> Self

Override the outer ring colour. Accepts a [Color], a theme role, or a Signal<Color>. Has no effect unless Self::border is also set to a positive width.

pub fn presence(self, presence: AvatarPresence) -> Self

Show a presence indicator dot. Pass AvatarPresence::Online, Offline, Away, or Busy.

pub fn presence_corner(self, corner: AvatarCorner) -> Self

Choose which corner the presence dot occupies. Default: AvatarCorner::BottomTrailing.

pub fn label(self, label: impl Into<LocalizedString>) -> Self

Override the accessible name. When unset:

• image-mode → alt if set, else the initials, else “Avatar”
• initials-mode → the initials.

pub fn alt(self, alt: impl Into<LocalizedString>) -> Self

Image alt text — distinct from label so a clickable avatar can have a button label like “Open user menu” while still describing the image as “Jane Doe”.

pub fn a11y_hidden(self) -> Self

Hide from the a11y tree entirely. Use only when an adjacent label conveys the avatar’s meaning.

pub fn on_activate_fn(self, f: impl Fn(&mut EventContext<'_>) + 'static) -> Self

Make the avatar activable. Promotes the a11y role to Role::Button and adds Action::Click / Action::Focus. Tap, Enter, and Space all fire the closure. Cursor changes to Pointer on hover.

pub fn has_popup(self, kind: HasPopup) -> Self

Declare that this avatar is a disclosure trigger for a popup (typically HasPopup::Menu for a user-menu trigger). Surfaces via set_has_popup in the a11y node so screen readers announce the avatar as “menu button” / “has popup”. Only takes effect when paired with .on_activate_fn(...) — without an activation handler the avatar isn’t a trigger.

pub fn expanded_when(self, signal: impl Into<Prop<bool>>) -> Self

Bind a signal reporting whether this avatar’s popup is currently visible. The wrapping Popover / overlay manager owns the signal and flips it on show / dismiss; Avatar reads it in accessibility() to publish set_expanded. Only meaningful alongside .has_popup(...).

pub fn tooltip(self, text: impl Into<LocalizedString>) -> Self

Attach a plain single-line tooltip shown after the hover delay. Mutually exclusive with Self::rich_tooltip, Self::rich_tooltip_content, and Self::composite_tooltip — this call clears the other three slots.

pub fn rich_tooltip(self, key: impl Into<String>) -> Self

Attach a rich tooltip identified by a registry key. The tooltip content is resolved from the application’s TooltipRegistry at hover time. Mutually exclusive with the other tooltip setters — this call clears the other three slots.

pub fn rich_tooltip_content(self, content: TooltipContent) -> Self

Attach a rich tooltip from inline crate::tooltip::TooltipContent without a registry key. Mutually exclusive with the other tooltip setters — this call clears the other three slots.

pub fn composite_tooltip(self, content: impl Widget + 'static) -> Self

Attach a composite tooltip whose body is an arbitrary widget tree. Shown after the longer tooltip_delay_heavy delay. Mutually exclusive with the other tooltip setters — this call clears the other three slots.

pub fn name_signal(self, signal: Signal<String>) -> Self

Bind the user’s display name to a signal. The displayed initials are auto-derived from the current value (derive_initials), and the same value is used as the hash seed for the background tint. Bound at BindingLevel::Rebuild so the inner children regenerate on flip — the canonical login-flow pattern:

let user_name: Signal<String> = ctx.signal(String::new());
Avatar::with_initials(lit!("?"))        // logged-out fallback
    .name_signal(user_name.clone())
    .image_signal(user_avatar_signal)

pub fn image_signal(self, signal: Signal<Option<Rc<RasterIcon>>>) -> Self

Bind the image source. None ⇒ initials fallback. Each non-None value is masked to the configured AvatarShape by the inner ImageWidget. Bound at BindingLevel::Rebuild.

pub fn alt_signal(self, signal: Signal<Option<String>>) -> Self

Bind the image alt text. Bound at BindingLevel::AccessibilityOnly — only the screen-reader projection is affected.

pub fn label_signal(self, signal: Signal<Option<String>>) -> Self

Bind the accessible label. Bound at BindingLevel::AccessibilityOnly.

pub fn presence_signal(self, signal: Signal<Option<AvatarPresence>>) -> Self

Bind the presence indicator. None hides the dot. Bound at BindingLevel::Rebuild — the dot’s colour and the a11y description flip together so a rebuild keeps both layers in sync.

Trait Implementations

impl Debug for Avatar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Widget for Avatar

fn build(&mut self, ctx: &mut BuildContext<'_>) -> Vec<WidgetId>

Compose child widgets. Called once after the widget is placed in the arena, and again on environment change (theme switch, locale switch). Takes &mut self — store child IDs, signal handles, any state needed later. Returns the list of root child IDs (empty for leaf widgets).

fn layout_response( &self, _proposal: SizeProposal, _ctx: &LayoutContext<'_>, ) -> LayoutResponse

Respond to the parent’s size proposal with this widget’s wanted size, grow/shrink weights, and compression floor (see [LayoutResponse]).

fn place_children( &self, bounds: Rect, _proposal: SizeProposal, children: &mut [WidgetPlacement], _ctx: &LayoutContext<'_>, )

Position children within the allocated bounds.

fn accessibility(&self, builder: &mut AccessNodeBuilder)

Declare this widget’s accessibility identity.

fn children(&self) -> Vec<WidgetId>

Return the child widget IDs that this widget manages.

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

Concrete type name of this widget (e.g. "teksilo_widgets::button::Button"). The default implementation resolves at the impl site via std::any::type_name::<Self>(), so calls through &dyn Widget correctly dispatch to the monomorphized fn for the concrete type — getting the concrete name through the vtable without per-impl boilerplate.

fn cacheable_layout(&self) -> bool

Whether this widget’s layout_response may be memoized by the per-pass layout cache. Defaults to true.

fn paint(&self, _bounds: Rect, _canvas: &mut Canvas, _ctx: &PaintContext<'_>)

Draw the widget’s visual representation.

fn wants_after_paint(&self) -> bool

Whether this widget wants its after_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t aggregate descendant geometry.

fn after_paint(&self, _view: &WidgetTreeView<'_>, _ctx: &PaintContext<'_>)

Called once per frame after this widget’s subtree has finished painting. Receives a read-only view of the layout-resolved arena so a parent can read its descendants’ final bounds — e.g. TitleBar aggregates its drag region and control-button rects into a single HitRegions payload for the Windows backend’s WM_NCHITTEST.

fn wants_post_paint(&self) -> bool

Whether this widget wants its post_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t draw a foreground over their children.

fn post_paint( &self, _bounds: Rect, _canvas: &mut Canvas, _ctx: &PaintContext<'_>, )

Draw a foreground layer over this widget’s children.

fn wants_descendant_redirects(&self) -> bool

Whether this widget wants the AT walker to consult its a11y_redirect_descendant hook for every descendant during AT tree emission, not just its direct arena children.

fn a11y_redirect_descendant( &self, _self_id: WidgetId, _descendant: WidgetId, ) -> Option<NodeId>

Optional redirection hook for AT-tree placement of a child.

fn accessible_title_hint(&self) -> Option<String>

Suggest an accessible title to an enclosing container that wraps this widget as content — typically a modal / dialog shell that wants to propagate the inner content’s visible title as the shell’s own accessible name.

fn initial_focus_hint(&self) -> Option<WidgetId>

Optional hint that directs initial focus to a specific descendant when this widget is the root of a deferred-built modal surface.

fn accessibility_children(&self) -> Option<Vec<WidgetId>>

Optional override for the child ORDER presented to assistive technology, when it must differ from the paint / z-order child order returned by children.

fn as_any(&self) -> Option<&(dyn Any + 'static)>

Downcast hook. Default implementation returns None; concrete widgets override with Some(self) when they want to expose their concrete type to test-level introspection or reflection. The trait already bounds on std::any::Any so concrete types satisfy the 'static requirement.

fn as_any_mut(&mut self) -> Option<&mut (dyn Any + 'static)>

Mutable counterpart of as_any. Default returns None; widgets that want to expose mutable state to tests (e.g. so a test can mutate a Scene inside a SceneView post-layout) override with Some(self). Should follow the same opt-in pattern as as_any: only widgets that opt into & introspection should opt into &mut.

fn clips_children(&self) -> bool

Whether this widget clips its children to its bounds.

fn focus_reveal_rect(&self, _bounds: Rect) -> Option<Rect>

The rectangle (in absolute tree coordinates) that best represents this widget when the framework reveals it into an ancestor scroll area on focus gain. Returning None (the default) reveals the widget’s whole bounds — correct for most controls.

fn hit_shape(&self, _local_point: Point, _bounds: Rect) -> bool

Whether the point lies inside this widget’s actual shape, not just its rectangular bounds. Consulted by hit-testing right after the bounds check: returning false for a point that is inside the bounding box makes the widget transparent to the click there, so it falls through to whatever sibling is painted underneath (the same machinery as a fully pass-through node, but shape-aware).

fn preserves_children_on_rebuild(&self) -> bool

How rebuild_single_widget treats this widget’s existing children when re-running its build().

fn tooltip_has_content(&self) -> bool

Whether this widget, used as tooltip content, currently has anything worth showing.

fn declare_shortcuts(&self) -> Vec<Shortcut>

Declare the rebindable keyboard shortcuts this widget exposes, without installing handlers. The framework calls this at arena insertion time (before build()) and at certain lazy boundaries (e.g. Switcher walks declarations on its not-yet-mounted Pending slots), so settings UIs and the ShortcutRegistry see the keystrokes the moment the owning container mounts — even if build() hasn’t run.

fn take_handler_set(&mut self) -> Option<HandlerSet>

Extract attached handler set from a WidgetWithHandlers wrapper. Called during arena insertion to transfer handlers to the WidgetNode. Default: returns None (no attached handlers).