Struct IconButton 

pub struct IconButton { /* private fields */ }

A square, icon-only, flat-surface button. See module docs for embedded vs stand-alone modes, the five sizes, and the two bistate toggle modes.

Implementations

impl IconButton

pub fn new(icon: IconWidget) -> Self

Create an icon button from a custom icon. Defaults to IconButtonSize::Default (24 dp) and stand-alone visual mode. Apply .embedded() for the JetBrains “built-in” dim look, and one of the size methods (.large() / .toolbar() / .hero()) or .size(...) to pick a different size.

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

Per-call style override. Replaces the theme-wide default IconButtonStyle for just this IconButton instance — same role as Button::style(...). The override fully owns the background + border + size composition; icon coloring stays on the widget.

pub fn style_shared(self, style: SharedIconButtonStyle) -> Self

Per-call style override from an already-shared [SharedIconButtonStyle] (Rc<dyn IconButtonStyle>). Same effect as style but takes the erased handle directly, so a host (e.g. a Toolbar applying one style to all its icon buttons) can share a single Rc instead of cloning a concrete style per button.

pub fn size_variant(&self) -> IconButtonSize

Returns the configured size variant. Used by wrappers like PopoverIconButton that need to reason about the trigger’s footprint at build time (e.g. to skip a corner decoration that wouldn’t fit at Compact).

pub fn is_embedded(&self) -> bool

Returns whether the button is in the JetBrains “built-in” / embedded color profile (Secondary at rest). Mirror getter to size_variant for wrappers that want to derive their own chrome colors from the same icon role.

pub fn share_interaction(self, signal: Signal<InteractionState>) -> Self

Bind the button’s internal interaction state to a caller-owned Signal<InteractionState> instead of letting build() allocate its own. Used by wrapper widgets like PopoverIconButton whose disclosure caret needs to match the icon’s color across hover / press / focus / disabled states.

The provided signal is reset to Disabled when enabled == false during build() so the shared signal honors the button’s enabled state without the caller having to seed it.

pub fn embedded(self) -> Self

Opt into the embedded visual treatment — the JetBrains “built-in button” look. Icon dims to Secondary at rest, brightens to Primary on hover, flashes Accent on press — designed to live inside another widget’s trailing slot (TextInput’s clear-X, ComboBox’s chevron) without competing visually with the host’s content. Default mode is stand-alone (icon at full visual weight, Primary always).

pub fn icon_role(self, role: impl Into<ColorProp>) -> Self

Override the icon’s tint with a static ColorProp. When set, the icon ignores embedded and the auto-derived idle/hover/press role cascade — its color is bound directly to this prop instead. Use for chrome whose host enforces a single text role across all of its sub-widgets (e.g. tab-bar scroll arrows that must match the tab strip’s idle_text_role regardless of hover state). Accepts Color, TextRole, Signal<Color>, or Signal<TextRole>.

It replaces the interaction cascade (idle / hover / press / focus), not the disabled substitution: a role passed here still resolves to [TextRole::Disabled] in a disabled subtree, like every other role-derived color (see ColorProp::resolve). That is what a disabled control should look like. When the tint is semantic state that stays true even though the button can’t be pressed — a save/sync indicator, a validation badge — wrap it: .icon_role(ColorProp::undimmed(role)).

pub fn focusable(self, on: bool) -> Self

Whether the button takes keyboard focus. Default true — the button is focusable when enabled. Set to false for embedded-control patterns where the parent owns focus and keyboard interaction goes through the parent (e.g. the close button inside a tab header — Tab moves between tabs, not onto their close buttons).

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

Attach a tooltip that appears after a hover delay. Required — the tooltip text doubles as the AT name for icon-only buttons.

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

Attach a rich tooltip resolved from the app-wide tooltip registry. See Button::rich_tooltip.

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

Attach a rich tooltip driven by inline TooltipContent.

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

Attach a composite tooltip — third tier, hosting an arbitrary widget tree. See Button::composite_tooltip.

pub fn composite_tooltip_boxed(self, content: Box<dyn Widget>) -> Self

Attach a composite tooltip from an already-boxed widget — the boxed twin of composite_tooltip, for hosts that build the body via a Fn() -> Box<dyn Widget> factory (e.g. a ToolbarAction).

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

Set the enabled state, statically or reactively. Disabled buttons ignore input and dim their icon (handled by the framework’s PaintContext::effective_enabled). Forwarded into the arena via ctx.enabled_when(self_id, self.enabled.clone()) at build time — a bound signal updates live as it changes.

For a reactive enabled state — e.g. a toolbar button that enables only when the caret is inside a table — pass a Signal<bool> here, or call ctx.enabled_when(button_id, my_signal) from the composing widget’s build() instead of (or in addition to) this builder. Both routes write to the same arena enabled_state; an external enabled_when registered after this builder runs wins (last-write semantics) and updates reactively from the signal.

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

Set the size variant. Most callers prefer the named shortcuts large / toolbar / hero; use .size(...) for Compact or for programmatic size selection.

pub fn toolbar(self) -> Self

Shortcut for .size(IconButtonSize::Toolbar) (30 dp) — the IntelliJ side-toolbar density (left / right / top window edges).

pub fn large(self) -> Self

Shortcut for .size(IconButtonSize::Large) (40 dp) — emphasized stand-alone buttons in rich menus and detail panes.

pub fn hero(self) -> Self

Shortcut for .size(IconButtonSize::Hero) (50 dp) — hero / landing-screen CTAs.

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

Closure invoked on activation. Fires after the toggle signal (if any) is flipped, so apps observing the closure see the post-flip state.

pub fn toggle(self, state: Signal<bool>) -> Self

Enable surface-tint bistate: clicking flips state and the background reads as SurfaceRole::Selected while state == true. The icon glyph is unchanged. Pin / select / lock-toggle pattern. on_activate_fn, if any, still fires after the flip.

For the eye / eye-off pattern where the icon glyph also changes, use toggle_with_icon instead.

pub fn toggle_with_icon( self, state: Signal<bool>, toggled_icon: IconWidget, ) -> Self

Enable surface-tint plus icon-swap bistate: clicking flips state, the background flips to Selected, and the icon swaps to toggled_icon. The visibility-toggle pattern (eye ↔ eye-off). For surface-only bistate (icon stays the same), use toggle.

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

Declare that this button is a disclosure trigger for a popup (menu, dialog, listbox, …). Surfaced via set_has_popup in the a11y node so screen readers announce it as opening the named popup kind. Wired automatically by PopoverIconButton.

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

Bind a signal reporting whether this button’s popup is currently visible. The popover wrapper owns the signal and flips it on show / dismiss; IconButton reads it in accessibility() to publish set_expanded. Only meaningful alongside has_popup.

pub fn browse() -> Self

Browse button (ellipsis icon). Opens a file/directory chooser.

pub fn expand() -> Self

Expand button (diagonal resize arrows). Enlarges a constrained field.

pub fn search() -> Self

Search button (magnifier icon). Triggers a search.

pub fn copy() -> Self

Copy button (clipboard icon). Copies the field content.

pub fn clear() -> Self

Clear button (X icon). Clears the field content.

pub fn add() -> Self

Add button (plus icon). Adds a new entry.

pub fn bell() -> Self

Notification bell. Used by NotificationCenterButton — the bell-icon trigger that opens the notification log popover.

pub fn menu() -> Self

Menu / hamburger button (three horizontal bars). Used by the collapsible MenuBar as the collapsed representation that reveals the bar when activated. Advertises HasPopup::Menu for assistive technology.

pub fn more() -> Self

“More actions” / overflow button — three vertical dots (the kebab ⋮). The conventional trigger for a per-item options menu (view-header …, list-row overflow). Advertises HasPopup::Menu for assistive technology. Pair with a PopoverIconButton + MenuList (use .bare() so the menu isn’t wrapped in a second popover surface).

pub fn visibility_toggle(visible: Signal<bool>) -> Self

Visibility toggle (eye / eye-off). Toggles password visibility. Uses the icon-swap bistate mode internally — the icon advertises the expected action, matching the prevailing password-field convention (1Password, Bitwarden, KeePass, Chrome, GitHub): eye (open) while the value is hidden, suggesting “click to reveal”; eye_off (closed) once revealed, suggesting “click to hide”. set_toggled still reports the literal current state, so AT readers are not misled.

For a current-state-instead semantics (icon shows what IS), build your own with toggle_with_icon and the eye glyphs in the opposite order.

The visible signal is flipped on each click. The host widget reads it to decide whether to mask or show the text.

Trait Implementations

impl Debug for IconButton

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

Formats the value using the given formatter.

impl PopoverTrigger for IconButton

fn default_has_popup() -> HasPopup

The has_popup kind announced by AT when the caller doesn’t override it. Button → [HasPopup::Dialog]; IconButton → [HasPopup::Menu].

fn default_show_caret() -> bool

Whether the disclosure caret is painted by default. Button → false (text buttons advertise via an inline trailing chevron); IconButton → true (icon-only triggers have no label slot).

fn suppress_caret(&self) -> bool

Whether the caret must be suppressed for this trigger regardless of the flag (e.g. IconButton at Compact has no room). Default: never suppressed.

fn caret_role(&self, interaction: &Signal<InteractionState>) -> Signal<TextRole>

The TextRole the disclosure caret tints with, derived from the shared interaction signal so the caret and trigger tint together across hover / press / focus / disabled. Only called when a caret is shown.

fn with_shared_interaction(self, signal: Signal<InteractionState>) -> Self

Share an externally-allocated interaction signal so the caret colour tracks the trigger’s state (hover / press / focus / disabled) exactly.

fn with_has_popup(self, kind: HasPopup) -> Self

Annotate the trigger with the given has_popup kind for AT.

fn with_expanded_when(self, open: Signal<bool>) -> Self

Bind the trigger’s set_expanded disclosure state to open.

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

Install the popover’s open/close handler as the trigger’s activate callback.

fn has_on_activate(&self) -> bool

Return true if the trigger already has an activate handler set by the caller — the wrapper replaces it and will warn at build time.

impl Widget for IconButton

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).