Struct TabWidget 

pub struct TabWidget { /* private fields */ }

All-in-one tabbed container. Builds a TabBar above a Switcher of content panes, sharing one selection signal.

Implementations

impl TabWidget

pub fn new(selected: Signal<Option<TabId>>) -> Self

Construct an empty TabWidget. Selection is None until the first static_tab(...) / dynamic_model(...) adds a tab and the framework activates it.

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

Enable or disable the whole widget. A disabled TabWidget greys out and stops accepting focus / selection / keyboard input (arena-gated). Distinct from per-tab TabInfo::enabled.

pub fn bar_visibility( self, visibility: impl Into<Prop<TabBarVisibility>>, ) -> Self

Set the tab-strip visibility policy (default TabBarVisibility::Always). Use TabBarVisibility::WhenMultiple to hide the strip while a single tab is present, or TabBarVisibility::Never when an external selector (e.g. a docking activity rail) drives selection.

Accepts a plain TabBarVisibility or a Signal<TabBarVisibility>. Bound reactively, the strip appears and disappears in place — the TabWidget itself is never torn down, so per-tab content state (caret, scroll offset, focus) survives the flip. That is the point of binding rather than swapping two TabWidgets in a Switcher: an app-level “hide the chrome” mode must not cost the user their place in the document.

A derived signal (.map(..) / .zip(..)) is fine here: binding resolves through to the mutable roots and never calls observe.

pub fn tab_bar_height(self, dp: f32) -> Self

Override the tab-strip height (its cross-axis extent). None / unset keeps the style’s editor_tab_height (50 dp). Use for a denser strip — e.g. dock side panels.

pub fn compact_bar(self) -> Self

Shorthand for a compact (38 dp) tab strip — denser than the standard 50 dp editor strip. Equivalent to self.tab_bar_height(38.0).

pub fn vertical(self) -> Self

Configure the bar to render vertically — pills stacked top-to-bottom on the leading edge, content fills the trailing area (sidebar / IDE-perspective convention). Equivalent to self.orientation(TabBarOrientation::Vertical).

pub fn horizontal(self) -> Self

Configure the bar to render horizontally — pills laid out left-to-right above the content (browser tab convention). This is the default.

pub fn orientation( self, orientation: impl Into<Prop<TabBarOrientation>>, ) -> Self

Set the bar orientation, statically or reactively. Passing a Signal<TabBarOrientation> replaces the internal orientation signal with the external one — lets a parent widget toggle orientation reactively (e.g. a “View → Vertical Tabs” toolbar button) without recreating the TabWidget.

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

Add a static tab — fixed for the widget’s lifetime, with a pre-built content widget. The content is registered in the arena on the TabWidget’s first build and memoized — subsequent rebuilds (caused by adjacent dynamic-model mutations) reuse the same pane WidgetId, preserving any internal state the content owns.

pub fn tab( self, label: impl Into<LocalizedString>, content: impl Widget + 'static, ) -> Self

Ergonomic shorthand for a title-only static tab: tab(label, content) is static_tab(TabInfo::new().title(label), content). label accepts tr!(...) (translated) or lit!(...). This is the method the teksu! tab: slot lowers to (tab: lit!("Overview"), Card { … }).

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

WidgetId twin of tab — tab_id(label, id) is static_tab_id(TabInfo::new().title(label), id). This is what the teksu! tab: slot lowers to when its content is an id binding (#{…} / name = Element).

pub fn static_tab_factory( self, info: TabInfo, factory: impl Fn(&TabHandle) -> Box<dyn Widget> + 'static, ) -> Self

Add a static tab whose content is constructed by a factory closure. The factory is called once — on the slot’s first build — and the resulting pane is memoized just like static_tab.

pub fn static_tab_id(self, info: TabInfo, content_id: WidgetId) -> Self

Element-valued slot variant for the teksu! DSL — accepts a pre-registered widget id rather than a Box<dyn Widget>. Equivalent to static_tab with an already-built child; the id is wrapped in a tab pane on first build and the pane id is memoized thereafter.

pub fn static_tab_with_id( self, id: TabId, info: TabInfo, content: impl Widget + 'static, ) -> Self

Add a static tab with a caller-provided TabId — useful when external code (an app-event handler, a session-restore path, a deep link) needs to flip selection to this tab by id. The pane is memoized like static_tab.

pub fn static_tab_factory_with_id( self, id: TabId, info: TabInfo, factory: impl Fn(&TabHandle) -> Box<dyn Widget> + 'static, ) -> Self

Factory variant of static_tab_with_id.

pub fn dynamic_tab<S: Any + 'static>( self, kind: &'static str, factory: impl Fn(&TabHandle, &S) -> Box<dyn Widget> + 'static, ) -> Self

Register a dynamic-tab content factory keyed by kind. The <S> type parameter pins the payload type — the framework downcasts handle.payload to S before calling the factory and panics with a clear message on kind/payload mismatch, so Any never leaks into app code.

pub fn dynamic_model(self, model: ListModel<TabHandle>) -> Self

Connect the dynamic-tab data source. Mutations rebuild the dynamic-tab subtree; static tabs are unaffected.

pub fn tab_sizing(self, mode: TabSizing) -> Self

Set the per-tab sizing strategy as a static value. Internally stores it as a Signal<TabSizing> so the widget can be retrofitted to reactive control via Self::sizing without breaking existing call sites.

pub fn sizing(self, sizing: impl Into<Prop<TabSizing>>) -> Self

Bind the per-tab sizing strategy, statically or reactively — flipping a bound signal swaps between Shared / Independent / Fill live, with no rebuild on the parent’s part. The signal is bound at BindingLevel::Rebuild inside build; memoized panes survive the rebuild so per-tab state is preserved.

pub fn tab_display(self, mode: impl Into<Prop<TabDisplayMode>>) -> Self

Choose what every tab shows — icon, label, or both (TabDisplayMode), statically or reactively. A bound signal can be flipped to swap icon / text / icon+text live (the bar rebuilds, memoized panes survive), with no rebuild on the parent’s part. Bound at BindingLevel::Rebuild.

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

All-states shorthand for the per-tab background — every tab (selected, idle, hovered) paints this unless a per-state override is set. Accepts any Color, SurfaceRole, or Signal<Color> (via ColorProp). Default is transparent. To tint the bar’s backdrop instead, use bar_background.

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

Background for the selected tab. Falls back to tab_background, then transparent.

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

Background for the hovered (non-selected) tab. Falls back to tab_background, then transparent.

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

Background for idle tabs (not selected, not hovered). Falls back to tab_background, then transparent.

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

Set the bar-strip backdrop fill (behind headers, slots, arrows), independent of the per-tab backgrounds. Default transparent.

pub fn tab_dividers(self) -> Self

Draw a 1 dp divider between consecutive tabs. Off by default.

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

Like tab_dividers with an explicit colour (Color, BorderRole, or Signal<Color>). Implies tab_dividers().

pub fn active_indicator(self, position: TabIndicatorPosition) -> Self

Choose which edge the active-tab highlight indicator hugs. Default TabIndicatorPosition::OuterEdge; InnerEdge puts it below the label (horizontal) / trailing edge (vertical).

pub fn selected_text_role(self, role: TextRole) -> Self

Set the text role used for the label (and matching icon tint) on the selected tab. Default: [teksilo_tokens::TextRole::Primary] — the Int UI editor-strip convention. Override to e.g. [teksilo_tokens::TextRole::Accent] when the strip sits over a tinted surface.

pub fn idle_text_role(self, role: TextRole) -> Self

Set the text role used for the label (and matching icon tint) on idle tabs (not selected, not disabled). Default: [teksilo_tokens::TextRole::Secondary]. Disabled tabs always read as [teksilo_tokens::TextRole::Disabled] regardless of this setting.

pub fn min_tab_width(self, dp: f32) -> Self

Minimum scrollable-tab width in logical pixels. Default DEFAULT_MIN_TAB_WIDTH.

pub fn max_tab_width(self, dp: f32) -> Self

Maximum scrollable-tab width in logical pixels. Default DEFAULT_MAX_TAB_WIDTH.

pub fn pinned_tab_width(self, dp: f32) -> Self

Fixed width for pinned (icon-only) tabs in logical pixels. Default DEFAULT_PINNED_TAB_WIDTH.

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

Show or hide the leading/trailing scroll-arrow buttons when tabs overflow. Default (unset) uses the style’s preference.

pub fn overflow_button(self, mode: TabOverflowButton) -> Self

When the trailing “show all tabs” overflow dropdown appears. Default (unset) is TabOverflowButton::Auto — shown only when the tab headers overflow the bar’s viewport. See TabOverflowButton for Always / Never.

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

Convenience over overflow_button: true maps to TabOverflowButton::Always, false to TabOverflowButton::Never.

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

Allow drag-to-reorder of tabs within the bar. Default false. Setting on_reorder implies reorderable(true).

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

Install a close-tab handler. Receives the TabId of the closed tab (not its index — indices are presentation-only) and the firing [EventContext]. The latter lets the handler open a confirmation dialog (ctx.present_modal(MessageBox::confirm(...))), dispatch an intent, or otherwise route the close request before mutating the underlying model. To veto, do nothing in the handler; to confirm-then-close, only call the model mutator on accept.

If unset, the default behavior is to remove the tab from dynamic_model without a prompt (static tabs cannot be closed by default).

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

Install a reorder handler. Receives (moved_tab_id, destination_index, ctx) in the unified static-then-dynamic ordering. The firing [EventContext] lets the handler confirm or dispatch the reorder via a dialog / intent before mutating the model. If unset, the default behavior is to reorder within the dynamic region of dynamic_model. Implies reorderable(true).

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

Install a pin-toggle handler — receives (tab_id, new_pinned_flag, ctx) when the user drags a tab across the pinned ↔ unpinned boundary. The firing [EventContext] lets the handler confirm or dispatch the transition via a dialog / intent. Apps decide whether to actually mutate the tab’s info.pinned.

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

Opt into cross-TabWidget tab transfer (app-internal drag-and-drop between two tabbed containers). When enabled, this widget’s dynamic tabs can be dragged out to any other accepting TabWidget, and it accepts tabs dragged in from one, painting an insertion-line indicator between its tabs.

The dragged TabHandle moves intact — its Rc<dyn Any> payload (the heavy per-tab state) is preserved, not rebuilt — so the receiving widget must register a content factory for the tab’s kind via dynamic_tab.

Static tabs are excluded: they have no factory on a receiving widget, so they can never be transferred out (they still reorder in place if reorderable).

By default, accepting a tab inserts it into this widget’s dynamic_model and transferring one out removes it from this widget’s model. Override either side with on_tab_received / on_transfer_out. Default: off.

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

Override the target-side behaviour when a foreign tab is dropped onto this widget. Receives (handle, insertion_index, ctx) where insertion_index is within the dynamic tab region. The app inserts the handle into its own model. Implies accept_external_tabs(true).

If unset, the default inserts the handle into dynamic_model at the drop position.

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

Override the source-side behaviour after one of this widget’s tabs has been accepted by another TabWidget. Receives the transferred TabId; the app removes it from its own model. Implies accept_external_tabs(true).

If unset, the default removes the tab from dynamic_model.

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

Accept non-tab drops onto the tab bar — an in-app foreign drag (e.g. a file dragged from a TreeView, carrying app data) or an OS file/text/URL drop. The bar shows an insertion-line indicator while such a payload hovers; on drop, f runs with the raw [DragPayload], the insertion index within the dynamic region, and the firing context. Inspect the payload (get_typed::<T>() / files() / text() / uris()) and, e.g., push a new TabHandle into your dynamic_model; return true if accepted.

This is the “open a dropped file as a tab” hook (VS Code style). Independent of accept_external_tabs. OS drops also require TeksiloAppBuilder::install_external_dnd().

pub fn bar_leading_slot(self, w: impl Widget + 'static) -> Self

Place a widget on the leading edge of the tab strip (before the first tab). Memoized: registered once on first build, reused on rebuilds.

pub fn bar_trailing_slot(self, w: impl Widget + 'static) -> Self

Place a widget on the trailing edge of the tab strip (after the last tab and overflow button). Memoized like bar_leading_slot.

pub fn bar_leading_slot_id(self, id: WidgetId) -> Self

Element-valued variant of bar_leading_slot accepting a pre-registered WidgetId (for the teksu! DSL).

pub fn bar_trailing_slot_id(self, id: WidgetId) -> Self

Element-valued variant of bar_trailing_slot.

Trait Implementations

impl Debug for TabWidget

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

Formats the value using the given formatter.

impl Widget for TabWidget

fn preserves_children_on_rebuild(&self) -> bool

TabWidget memoizes the WidgetIds of its static-tab panes, dynamic-tab panes (keyed by TabId), and bar slots across rebuilds — internal mutable state (focus, scroll, animation, rich-text editor history, …) survives sibling mutations (dynamic-model push / remove / reorder, locale or theme changes that retitle live tabs). Without this opt-in, the framework’s default destroy_subtree step on rebuild would reap those memoized panes and the user would see static-tab content vanish the first time they opened or closed a dynamic tab.

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