Guide API
Skip to main content

Cluster

Struct Cluster 

Source
pub struct Cluster {
    pub state: ViewState,
    pub value: u32,
    pub sel: i32,
    pub enable_mask: u32,
    pub strings: Vec<String>,
    pub kind: ClusterKind,
    /* private fields */
}
Expand description

The cluster engine (state + layout + nav + draw + events).

Clusters of related toggles: CheckBoxes, RadioButtons, and MultiCheckBoxes.

§The seam

The three cluster kinds differ only in their box icon, marker characters, and how value is interpreted, so the polymorphism is modeled as data rather than separate behavior:

  • Cluster is the full engine — state + layout + nav + draw + events — and branches on its ClusterKind for the per-kind behavior. It is the only type that impls View with real bodies.
  • CheckBoxes / RadioButtons / MultiCheckBoxes are thin embed-and-delegate wrappers ({ cluster: Cluster }) whose impl View forwards every method to self.cluster. Their constructors build a Cluster with the right ClusterKind. This keeps named, familiar types while the logic lives once.

§Layout

size.y (the bounds height) is the column-break period: items fill top-to-bottom within a column, then wrap to the next column. A column is 6 + max-label-width cells wide (the [ ] icon is 5 cells plus a 1-cell gap). Label widths strip the ~-toggle hotkey marker, which is not a printed column.

§Marker / icon data

The box icons ([ ], ( )) and marker chars (X, the bullet •) live inline as per-kind data, with no theme edit needed.

§Mouse hold-tracking

Mouse-down begins a modal hold:

  • MouseDown: select the item under the cursor (if enabled), set tracking = true, and call Context::start_mouse_track. Do NOT press yet.
  • MouseMove arm (loop body): a no-op — the original only toggled cursor visibility while dragging, which has no TUI equivalent. Guarded by tracking.
  • MouseUp arm (post-loop): press only if the item under the release position is still the selected one — the same-item release-confirm. Clear tracking. Guarded by tracking.

The abs_origin field caches the view-local (0, 0) in absolute screen coords from the last draw, used by the capture to localize events.

§Value and help context

The typed value protocol (value/set_value) is not implemented for clusters: their value/sel fields are read and written directly by their owning dialog rather than through the gather/scatter protocol. The original per-item help-context offset (help id plus selected index) does not map onto tvision-rs’s string-identity HelpCtx and is not modeled.

Embeds ViewState, impls View fully, and branches on kind for per-kind behavior. The concrete CheckBoxes / RadioButtons / MultiCheckBoxes wrappers delegate to an instance of this.

Most callers never construct a Cluster directly — they call CheckBoxes::new, RadioButtons::new, or MultiCheckBoxes::new, which pick the right ClusterKind and wrap the result. Use Cluster directly only when you need to inspect or mutate shared engine state (e.g. cluster.value, cluster.sel) via one of the named wrapper’s .cluster field.

§Turbo Vision heritage

Ports TCluster and its subclasses TCheckBoxes / TRadioButtons / TMultiCheckBoxes (tcluster.cpp, tcheckbo.cpp, tradiobu.cpp, tmulchkb.cpp). The abstract base with its per-kind virtual overrides becomes one engine branching on a closed ClusterKind enum, with the named subclasses as embed-and-delegate wrappers (deviations D1, D2). The palette AttrPairs become (lo, hi) Role pairs, and coordinates arrive view-local from the group so no manual localization is needed.

Fields§

§state: ViewState

View state (geometry, flags, cursor) — the composition target.

§value: u32

The current value of the cluster, interpreted per kind.

  • CheckBoxes: a bitmask — bit i is set when item i is checked. Read value & (1 << i) != 0 to test; the engine toggles bits via Space / mouse / hotkey.
  • RadioButtons: the index of the selected button (0-based). The engine writes value = item on every press or arrow-key move, so value is always the index of the one visible bullet.
  • MultiCheckBoxes: packed n-bit states — use multi_mark(i) (via the engine’s internal reader) to unpack item i’s state, or construct the packed word using the flags field documented on ClusterKind::MultiCheckBoxes.

Starts at 0 after construction. Write it directly when restoring saved state (e.g. re-loading a dialog); the next draw pass will reflect the new value without any explicit redraw call (the whole-tree redraw runs every event loop tick).

§sel: i32

The index of the currently-highlighted item (the selection cursor).

For CheckBoxes and MultiCheckBoxes this is purely the visual focus position — pressing Space toggles or cycles the highlighted item. For RadioButtons it mirrors value: moving the cursor also selects (the arrow keys update both sel and value together).

When restoring a RadioButtons from saved state, set both sel and value to the same index so the visual cursor starts on the pressed button.

§enable_mask: u32

Bitmask controlling which items are interactive; bit i set ⇔ item i is enabled.

Default after construction: 0xFFFF_FFFF (all 32 slots enabled). Use set_button_state to enable or disable items at runtime — it updates both this mask and the cluster’s selectable option (clearing selectable when every item is disabled). Only items 0–31 are represented; items 32 and above are always treated as disabled regardless of this field’s value.

§strings: Vec<String>

The item labels displayed next to each box, in construction order.

Each string may contain a ~ hotkey marker: "~A~lpha" displays “Alpha” with A as the accelerator key (activated by Alt+A or, when focused, by the plain letter A). The ~ characters are stripped from the visual column-width calculation.

The vector is filled column-major (item = column * size.y + row) by the layout engine — the insertion order here is the visual top-to-bottom, left-to-right reading order.

§kind: ClusterKind

The per-kind behavior selector; determines how value is interpreted and how draw renders each item. Set at construction via Cluster::new; do not change after construction (the named wrappers seal this at build time).

Implementations§

Source§

impl Cluster

Source

pub fn new(bounds: Rect, strings: Vec<String>, kind: ClusterKind) -> Self

Build a cluster from bounds, strings, and a ClusterKind.

Most callers should prefer the named constructors (CheckBoxes::new / RadioButtons::new / MultiCheckBoxes::new), which call this with the correct kind. Use Cluster::new directly only when you need to share the engine or construct a custom kind.

The constructed cluster starts with:

  • value = 0, sel = 0 — no item selected/checked.
  • enable_mask = 0xFFFF_FFFF — all items enabled.
  • Cursor at (2, 0) (inside the first box) and shown.
  • View options: selectable, first-click-aware, pre- and post-processing enabled (needed for hotkey delivery via the event pipeline).
Source

pub fn set_button_state(&mut self, a_mask: u32, enable: bool)

Enable or disable the items selected by a_mask and recompute the cluster’s selectability.

a_mask is a bitmask in the same layout as enable_mask: bit i set in a_mask selects item i. Pass enable = true to make those items interactive, false to grey them out (they will still be drawn but will not respond to keyboard or mouse input).

After updating enable_mask, this method recomputes whether the cluster as a whole is selectable: if every item (within the first count slots) is disabled, the cluster clears its selectable option so the focus order skips it entirely. Re-enabling any item restores selectability automatically.

ⓘ
// Grey out the second option (item index 1) in a two-item CheckBoxes.
my_checkboxes.cluster.set_button_state(1 << 1, false);

Trait Implementations§

Source§

impl View for Cluster

Source§

fn draw(&mut self, ctx: &mut DrawCtx<'_>)

Paint the cluster.

Per row i (the outer loop runs 0..=size.y; the extra i == size.y row writes at y == size.y, which put_char clips away — a harmless no-op kept for layout symmetry): blank the full width in the normal lo color, then for each item in the row (cur = j*size.y + i, j over the columns) whose column(cur) < size.x: pick the item color (disabled if disabled, selected if it is the selected item in a focused cluster, else normal), re-fill col..size.x in that color, draw the icon, the marker glyph at col+2 in the row’s lo color, and the label at col+5.

Ends by parking the cursor at (column(sel)+2, row(sel)) so the hardware cursor tracks the selection (surfaced via the base cursor request).

Source§

fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)

Handle keyboard and mouse events.

The mouse-down auto-select lives in Group, so this body starts at the selectable guard. On mouse-down: select the item and arm the mouse-track capture; press fires on mouse-up at a release inside the same item. On key-down: ctrl-to-arrow aliasing, the four arrow navigators (focused only), the Alt-hotkey / plain-letter accelerator scan, then focused-Space → press.

Source§

fn state(&self) -> &ViewState

Borrow the embedded ViewState (the view’s data members).
Source§

fn state_mut(&mut self) -> &mut ViewState

Mutably borrow the embedded ViewState.
Source§

fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)

Flip a propagating state flag and run its side effects. The base flips the flag and, for StateFlag::Focused, emits the focus broadcast (RECEIVED_FOCUS/RELEASED_FOCUS) via ctx. Read more
Source§

fn valid(&mut self, _cmd: Command, _ctx: &mut Context<'_>) -> bool

Whether the view is in a valid state for cmd (e.g. a modal end / focus release). Base is always true. Read more
Source§

fn set_modal_answer(&mut self, _cmd: Command)

Stash the user’s choice from an async modal message box this view requested via Context::request_message_box (the answer_to/RouteModalAnswer round-trip). Default: no-op. Overridden by views that drive a Yes/No/Cancel prompt out of valid (e.g. FileEditor caches it for the re-validate).
Source§

fn value(&self) -> Option<FieldValue>

This control’s current value as a FieldValue, or None for a view that carries no transferable data. Read more
Source§

fn set_value(&mut self, _v: FieldValue)

Load a typed FieldValue into this control. Read more
Source§

fn set_modal_data(&mut self, _data: FieldValue)

Deliver a finished modal’s typed result record to the view that launched it. Defaulted no-op; a launcher view overrides it to load the record. Two producers call it: Read more
Source§

fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)

Scatter a typed FieldValue into this control with a Context. Default: calls set_value (the context-free setter). Override when scatter needs deferred publishing (e.g. ListBox republishes its vertical scrollbar via focus_item).
Source§

fn awaken(&mut self)

Post-construction initialization hook. Called once after the view has been inserted into its group and the group’s layout is complete — the earliest point at which a view may safely resolve sibling ids or run initialization that requires a fully-wired tree. Override when a widget needs to do work that cannot happen during construction (e.g. reading a linked control’s current value). Base is a no-op.
Source§

fn size_limits(&self, owner_size: Point) -> (Point, Point)

The (min, max) size this view may take inside an owner of owner_size. Read more
Source§

fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect

The new bounds after the owner resized to owner_size (delta = new - old). Computes the size limits via the overridable size_limits hook — so a widget override (e.g. a window’s minimum) participates — then delegates the grow math to ViewState::calc_bounds (the single source). Returns the bounds; it does not apply them (change_bounds does).
Source§

fn change_bounds(&mut self, bounds: Rect)

Apply bounds to this view and propagate as needed. Read more
Source§

fn on_bounds_changed(&mut self, _ctx: &mut Context<'_>)

Called by the pump after change_bounds is applied via Deferred::ChangeBounds — provides a Context for re-publishing state that depends on the new bounds (e.g. scrollbar params). Default implementation is a no-op. Read more
Source§

fn cursor_request(&self) -> Option<Point>

The view-local hardware-cursor position this view wants shown, or None to hide it. Base: Some(cursor) iff the view is focused with a visible cursor, else None. Read more
Source§

fn caret_size(&self) -> u8

The caret size this view wants while its cursor is shown, as a percentage of the character cell (1..=100). Base: CARET_INSERT (a block) when the cursor_ins state is set, else CARET_NORMAL (the normal caret). The event loop reads it along the same focused chain as cursor_request; Group overrides it to descend into its current child. Read more
Source§

fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>

Resolve id to a descendant of this view (never self — the parent identifies a view by id). A leaf has no descendants, so the base returns None; a Group overrides to search its children and recurse; a Group-embedding view delegates to its inner group. This is the “tree-walk via Context” — the uniform way the event loop / a capture handler acts on a view it holds only by id (move a window’s bounds, flip the dragging flag, …).
Source§

fn remove_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Remove the descendant named by id from whichever group owns it. Returns true if it was found+removed. Distinct from find_mut because removal happens in the owner’s child Vec (a view cannot remove itself — it doesn’t know its owner) and must run the owning group’s reset_current. Base: false (a leaf owns nothing).
Source§

fn focus_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool

Focus (select) the descendant named by id within whichever group owns it — the tree-op behind a label focusing its linked control. Returns true if id was found in this subtree (selectable or not — finding it stops the walk). Distinct from find_mut because focusing happens in the owning group (a view cannot select itself within itself): the owning Group calls focus_child after applying the selectable gate. Base: false (a leaf owns nothing). Read more
Source§

fn has_focusable_leaf(&self) -> bool

Whether this view’s subtree contains a focusable leaf (visible, enabled, selectable). Base: whether THIS view is itself a focusable leaf; Group overrides to recurse into children; wrapper views delegate. Used by the hierarchical Tab traversal to skip selectable-but-empty subtrees.
Source§

fn focus_to_edge(&mut self, backward: bool, ctx: &mut Context<'_>) -> bool

Focus the first (Tab, backward = false) or last (Shift-Tab, backward = true) focusable leaf in this view’s subtree, establishing the full focus path down to it. Returns true if a focusable leaf was focused. Read more
Source§

fn reset_current(&mut self, _ctx: &mut Context<'_>)

Establish this view’s INTERNAL currency — for a group-bearing view, set its current child to the first visible+selectable child. The insert-time currency cascade cannot run inside the context-less Group::insert, so exec_view calls this on a freshly-inserted modal BEFORE focusing it, so the modal’s first selectable child is current on open (otherwise the modal is keyboard-dead until a nav event — see the seam note in exec_view). Base: no-op (a leaf has no internal currency); Group overrides; Window/Dialog delegate.
Source§

fn settle_currency(&mut self, _ctx: &mut Context<'_>)

Run any pending insert-time reset-current cascades in this subtree. Read more
Source§

fn set_visible_descendant( &mut self, id: ViewId, visible: bool, ctx: &mut Context<'_>, ) -> bool

Tree-op: set the visible flag of the descendant named by id from its OWNING group, running the owning group’s currency tail. Toggling visibility on a selectable view re-picks the owner’s current child, in both directions (show and hide). Returns true if id was found in this subtree. Read more
Source§

fn number(&self) -> Option<i16>

The window number for Alt-N selection. Base views are unnumbered (None); Window overrides to return its number when > 0 (0 means unnumbered → None).
Source§

fn grabs_focus_on_click(&self) -> bool

Whether a mouse-down inside this view should auto-select (focus) it — the per-view opt-out for the group’s mouse-down auto-select (see Group::route_event). Default true (the common case); a Button overrides to return its grab-focus flag. A view returning false is not focused by a click but still receives the click (so it can act, e.g. press, without becoming the current view).
Source§

fn select_window_num(&mut self, num: i16, ctx: &mut Context<'_>) -> bool

Tree-op: ask this subtree to select the window numbered num. Returns whether one matched. Consistent with the find_mut / remove_descendant tree-op family: the live loop holds a subtree only by id (here, the desktop) and asks it to act. Default: no-op (false). Desktop overrides.
Source§

fn tile(&mut self, _r: Rect)

Tree-op: lay this subtree’s tileable windows out in a grid (the tile command). Base: no-op (only Desktop lays out windows). r is the desktop-local layout rect. Mirrors select_window_num: the live loop drives the desktop by id through &mut dyn View.
Source§

fn cascade(&mut self, _r: Rect)

Tree-op: lay this subtree’s tileable windows out cascaded (the cascade command). Base: no-op; Desktop overrides.
Source§

fn apply_scroll_sync( &mut self, _h: Option<i32>, _v: Option<i32>, _ctx: &mut Context<'_>, )

The shared scrollbar read-sync broker hook. Defaulted no-op; scroll-aware widgets override it to apply a freshly-read scrollbar delta to themselves. The pump passes the horizontal/vertical scrollbar values (None if that bar is absent or unresolved), each read via View::value. Overridden by the list viewers (delegate to list_viewer::apply_scroll), Scroller, the outline viewer, and the editor — every sibling-scrollbar read sync routes through this one method instead of a pump downcast. Read more
Source§

fn update_menu_commands(&mut self, _disabled_cmds: &CommandSet)

The menu command-graying broker hook. Defaulted no-op; menu views override to re-gray their menu tree against the program’s live disabled-command set (denylist — the argument is the set of commands currently disabled; an item grays iff its command is in it). The free fn menu::menu_view::update_menu_commands implements the re-gray walk. Read more
Source§

fn set_menu_current(&mut self, _current: Option<usize>)

The menu-highlight write-back hook. Defaulted no-op; menu views (MenuBar / MenuBox) override to set their MenuViewState::current — the write-only display cache their draw reads to pick the selected colour. Read more
Source§

fn get_help_ctx(&self) -> HelpCtx

The effective help context for status-line switching. Returns HelpCtx::DRAGGING while the view is being dragged, otherwise the view’s own ViewState::help_ctx. Read more
Source§

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

Downcast hook for the rare parent→child push that needs the concrete type (e.g. a window pushing its zoomed flag to its frame). Base returns None; only views that must be reached concretely override it. (Any requires 'static, which every view is.)
Source§

fn descendant_global_bounds(&self, _id: ViewId, _acc: Point) -> Option<Rect>

Resolve descendant id to its absolute bounds, given acc = this view’s own absolute origin. Base returns None (a leaf owns no descendants); a Group overrides to walk its children accumulating origins, and a Group-embedding view delegates to its inner group. The THistory open path needs its linked input line’s bounds in the root/absolute frame, because exec_view root-inserts the modal and the modal frame hit-tests in absolute coords (the documented ROOT-INSERT + (0,0) caveat). Mirrors find_mut’s recursion but returns geometry, not a borrow.
Source§

fn set_indicator_value(&mut self, _location: Point, _modified: bool)

The editor→indicator status-push broker hook. Defaulted no-op; the editor’s status Indicator overrides it to store the new cursor location + modified flag. Driven by Deferred::IndicatorSetValue: the editor (a leaf) cannot reach its indicator sibling inline, so it requests this and the pump calls the method by id — virtual dispatch, not a downcast.
Source§

fn apply_page_sync(&mut self, _idx: usize, _ctx: &mut Context<'_>)

The tab-bar→page-stack switch broker hook. Defaulted no-op; PageStack overrides it to make page idx active. Driven by Deferred::PageStackSync: the pump reads the bound tab bar’s value and calls this method by id — virtual dispatch, not a downcast.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

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

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

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

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync> ⓘ

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.