Struct MenuItem 

pub struct MenuItem { /* private fields */ }

A single command row in a MenuList or context menu.

See the module documentation for the full mode table, mnemonic syntax, and submenu construction pattern.

Implementations

impl MenuItem

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

Create a plain menu item with the given label and no action yet.

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

Closure invoked on activation. Note: shortcut label auto-lookup is not available with this variant since there is no typed command to look up.

pub fn label(&self) -> String

Read the item’s display label. Exposed so SplitButton (and any other compound widget that embeds a MenuItem) can mirror the label in its own chrome.

pub fn label_localized(&self) -> LocalizedString

Like label but returns the unresolved [LocalizedString], so embedders can mirror the label reactively (re-resolving on a locale switch) instead of freezing a snapshot.

pub fn action(&self) -> Option<Rc<dyn Fn(&mut EventContext<'_>)>>

Clone out a shared handle to the activation closure. Returns None when this MenuItem has no action (e.g. it’s a submenu trigger). The returned Rc aliases MenuItem’s own internal handle — invoking it has the same effect as the user clicking this menu item (minus the overlay dismissal that the tap handler also performs).

pub fn icon(self, icon: IconWidget) -> Self

Set a leading icon.

pub fn icon_keeps_color(self) -> Self

Keep the icon’s own colour rather than tinting it with the row’s.

A menu icon normally says the same thing as the label beside it, so it takes the row’s text role and follows it through hover, press and disabled — which is why icon recolours whatever it is handed. Some icons are not that. A tag’s swatch, a status light, a colour a person chose: there the colour is the content, and tinting it to the menu’s foreground deletes the only thing the icon was there to say.

Opt-in, because the default is right for nearly every row, and keeping a colour has two costs the caller takes on:

• It does not follow the highlight. On a style whose highlighted row is a solid accent fill (the macOS recipe), the icon has to carry its own contrast against that fill as well as against the menu’s surface.
• It does not dim when the row is disabled — if it is a literal colour. That is ColorProp’s own rule everywhere, not a special case here: Static and Bound ignore the enabled state, while every role variant substitutes its disabled counterpart. An icon that should dim should be given a role instead, and then it does not need this at all.

Ignored in the check and radio modes, which draw an indicator glyph of the framework’s own rather than the caller’s icon.

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

Set a trailing shortcut label (e.g., “Ctrl+X”). Shortcut labels are typically not translated (they’re the key combination literal), so this accepts a plain string.

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

Set a trailing descriptive hint (e.g. “inside”, “after parent”) — a secondary phrase explaining what the item will do, rendered in the same trailing slot as an accelerator but semantically unrelated to one.

Prefer this over shortcut_label for any trailing text that is not a key combination. It differs in two ways that matter:

• it takes a [LocalizedString], so a tr!(...) hint re-resolves on a live locale change instead of being frozen at build time;
• it is announced as the item’s accessible description, not as keyboard_shortcut — a screen reader would otherwise read the phrase out as if it were a chord to press.

Independent of the accelerator: an item may carry both, in which case the chord renders first and the hint follows it.

pub fn for_shortcut(self, id: &'static str) -> Self

Bind the trailing shortcut label to a registered Shortcut by its stable id. At build time the effective primary keystroke is rendered; rebinds performed through ShortcutRegistry rebuild this item automatically via the registry’s version signal.

A manual shortcut_label takes precedence when both are set.

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

Set the enabled state — static or signal-bound. A bound Signal<bool> enables/disables the item reactively (paint and AT follow), so MenuItem::new(...).enabled(can_save_signal) greys out live without a rebuild. Cursor is always Pointer (see build); disabled items are gated by the arena before hover runs, so a NotAllowed cursor cannot be applied from a build-time snapshot of this prop either.

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

Per-call style override. Replaces the theme-wide default MenuItemStyle for just this MenuItem instance.

pub fn text_style(self, style: impl Into<TextStyleProp>) -> Self

Override the label’s text style (font, size, weight). Accepts a TextStyleRole, a TextStyle, or a Signal of either. Default (unset) is TextStyleRole::Body.

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

Override the label text color. Accepts Color, a role, or a Signal of either. Default (unset) is the interaction/enabled cascade; setting this replaces that cascade (the hover / disabled tint no longer applies), so reserve it for chrome that enforces a fixed text role.

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

Attach a tooltip that appears after a hover delay, same mechanism as Button::tooltip.

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

Attach a rich tooltip resolved from the app-wide tooltip registry. Body text supports inline markup ([label](url), *italic*, **bold**); the entry’s shortcut and long-form “more” fields are rendered automatically.

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 submenu( label: impl Into<LocalizedString>, factory: impl Fn() -> Box<dyn Widget> + 'static, ) -> Self

Create a submenu trigger item. The factory is invoked during build() to pre-create the submenu content (typically a MenuList), which is kept dormant until the hover delay elapses.

pub fn submenu_delay(self, delay: Duration) -> Self

Set a custom submenu open delay (default: 200ms).

pub fn is_submenu(&self) -> bool

Whether this is a submenu trigger.

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

Bind this item to a two-state Signal<bool>. The item renders Role::MenuItemCheckBox; activation flips the signal. By Windows convention, the leading icon slot becomes a checkmark when the signal is true, blank otherwise.

Mutually exclusive with check_state and radio — last call wins.

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

Render Role::MenuItemCheckBox whose checkmark reflects state read-only: activation does NOT write the signal — the truth lives elsewhere (a model / method), and this item’s on_activate/intent is responsible for the change, after which state updates the checkmark reactively. Use for “View ▸ Sidebar / Full Screen”-style commands that mirror externally-owned state (e.g. DockingModel::dock_open_signal), where two-way checked would fight the model.

Mutually exclusive with the other check / radio binders — last call wins.

pub fn check_state(self, state: Signal<CheckState>) -> Self

Bind this item to a tri-state Signal<CheckState>. The item renders Role::MenuItemCheckBox; activation cycles Unchecked ↔ Checked (per Windows / Checkbox convention: Indeterminate is reserved for external sources like TreeCheckedModel; clicking from Indeterminate promotes to Checked).

The leading-slot glyph is checkmark for Checked, dash for Indeterminate, blank for Unchecked — matching the Windows mixed-state convention.

Mutually exclusive with checked and radio — last call wins.

pub fn radio(self, value: usize, selected: Signal<usize>) -> Self

Bind this item to a radio group via a shared Signal<usize>. Activation writes value into selected; all radio items sharing the same selected signal observe the change and update their leading-slot dot accordingly. The item renders Role::MenuItemRadio.

For “2 of 3”-style AT announcement, the enclosing MenuList groups radio items by selection-signal identity and emits push_to_radio_group relationships automatically — no app-side wiring required.

Mutually exclusive with checked and check_state — last call wins.

Trait Implementations

impl Debug for MenuItem

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

Formats the value using the given formatter.

impl Widget for MenuItem

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

Opt into reflection so MenuList::build can downcast a pending boxed item and install its radio group buffer before the item is added to the arena.

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 as_any_mut(&mut self) -> Option<&mut dyn Any>

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