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:
Clusteris the full engine — state + layout + nav + draw + events — and branches on itsClusterKindfor the per-kind behavior. It is the only type thatimplsViewwith real bodies.CheckBoxes/RadioButtons/MultiCheckBoxesare thin embed-and-delegate wrappers ({ cluster: Cluster }) whoseimpl Viewforwards every method toself.cluster. Their constructors build aClusterwith the rightClusterKind. 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 callContext::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 bytracking.
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: ViewStateView state (geometry, flags, cursor) — the composition target.
value: u32The current value of the cluster, interpreted per kind.
CheckBoxes: a bitmask — bitiis set when itemiis checked. Readvalue & (1 << i) != 0to test; the engine toggles bits via Space / mouse / hotkey.RadioButtons: the index of the selected button (0-based). The engine writesvalue = itemon every press or arrow-key move, sovalueis always the index of the one visible bullet.MultiCheckBoxes: packed n-bit states — usemulti_mark(i)(via the engine’s internal reader) to unpack itemi’s state, or construct the packed word using theflagsfield documented onClusterKind::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: i32The 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: u32Bitmask 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: ClusterKindThe 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
impl Cluster
Sourcepub fn new(bounds: Rect, strings: Vec<String>, kind: ClusterKind) -> Self
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).
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
impl View for Cluster
Source§fn draw(&mut self, ctx: &mut DrawCtx<'_>)
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<'_>)
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 set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)
fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)
StateFlag::Focused, emits the focus broadcast
(RECEIVED_FOCUS/RELEASED_FOCUS) via ctx. Read moreSource§fn valid(&mut self, _cmd: Command, _ctx: &mut Context<'_>) -> bool
fn valid(&mut self, _cmd: Command, _ctx: &mut Context<'_>) -> bool
cmd (e.g. a modal end / focus
release). Base is always true. Read moreSource§fn set_modal_answer(&mut self, _cmd: Command)
fn set_modal_answer(&mut self, _cmd: Command)
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>
fn value(&self) -> Option<FieldValue>
FieldValue, or None for a view
that carries no transferable data. Read moreSource§fn set_value(&mut self, _v: FieldValue)
fn set_value(&mut self, _v: FieldValue)
FieldValue into this control. Read moreSource§fn set_modal_data(&mut self, _data: FieldValue)
fn set_modal_data(&mut self, _data: FieldValue)
Source§fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)
fn set_value_ctx(&mut self, v: FieldValue, ctx: &mut Context<'_>)
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)
fn awaken(&mut self)
Source§fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect
fn calc_bounds(&mut self, owner_size: Point, delta: Point) -> Rect
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)
fn change_bounds(&mut self, bounds: Rect)
bounds to this view and propagate as needed. Read moreSource§fn on_bounds_changed(&mut self, _ctx: &mut Context<'_>)
fn on_bounds_changed(&mut self, _ctx: &mut Context<'_>)
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 moreSource§fn cursor_request(&self) -> Option<Point>
fn cursor_request(&self) -> Option<Point>
None to
hide it. Base: Some(cursor) iff the view is focused with a visible cursor,
else None. Read moreSource§fn caret_size(&self) -> u8
fn caret_size(&self) -> u8
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 moreSource§fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>
fn find_mut(&mut self, id: ViewId) -> Option<&mut dyn View>
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
fn remove_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool
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
fn focus_descendant(&mut self, id: ViewId, ctx: &mut Context<'_>) -> bool
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 moreSource§fn has_focusable_leaf(&self) -> bool
fn has_focusable_leaf(&self) -> bool
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
fn focus_to_edge(&mut self, backward: bool, ctx: &mut Context<'_>) -> bool
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 moreSource§fn reset_current(&mut self, _ctx: &mut Context<'_>)
fn reset_current(&mut self, _ctx: &mut Context<'_>)
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<'_>)
fn settle_currency(&mut self, _ctx: &mut Context<'_>)
Source§fn set_visible_descendant(
&mut self,
id: ViewId,
visible: bool,
ctx: &mut Context<'_>,
) -> bool
fn set_visible_descendant( &mut self, id: ViewId, visible: bool, ctx: &mut Context<'_>, ) -> bool
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 moreSource§fn number(&self) -> Option<i16>
fn number(&self) -> Option<i16>
None);
Window overrides to return its number when > 0
(0 means unnumbered → None).Source§fn grabs_focus_on_click(&self) -> bool
fn grabs_focus_on_click(&self) -> bool
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
fn select_window_num(&mut self, num: i16, ctx: &mut Context<'_>) -> bool
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)
fn tile(&mut self, _r: Rect)
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)
fn cascade(&mut self, _r: Rect)
Desktop overrides.Source§fn apply_scroll_sync(
&mut self,
_h: Option<i32>,
_v: Option<i32>,
_ctx: &mut Context<'_>,
)
fn apply_scroll_sync( &mut self, _h: Option<i32>, _v: Option<i32>, _ctx: &mut Context<'_>, )
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 moremenu::menu_view::update_menu_commands
implements the re-gray walk. Read moreMenuBar / MenuBox)
override to set their
MenuViewState::current — the write-only
display cache their draw reads to pick the selected colour. Read moreSource§fn get_help_ctx(&self) -> HelpCtx
fn get_help_ctx(&self) -> HelpCtx
HelpCtx::DRAGGING while the view is being dragged, otherwise the
view’s own ViewState::help_ctx. Read moreSource§fn as_any_mut(&mut self) -> Option<&mut dyn Any>
fn as_any_mut(&mut self) -> Option<&mut dyn Any>
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>
fn descendant_global_bounds(&self, _id: ViewId, _acc: Point) -> Option<Rect>
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)
fn set_indicator_value(&mut self, _location: Point, _modified: bool)
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<'_>)
fn apply_page_sync(&mut self, _idx: usize, _ctx: &mut Context<'_>)
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§
impl Freeze for Cluster
impl RefUnwindSafe for Cluster
impl Send for Cluster
impl Sync for Cluster
impl Unpin for Cluster
impl UnsafeUnpin for Cluster
impl UnwindSafe for Cluster
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
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)
fn as_any(&self) -> &(dyn Any + 'static)
&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)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.