pub struct Label { /* private fields */ }Expand description
A single-line caption that links to a control: clicking it (or pressing
its ~-marked hotkey) focuses the linked control, and the label
highlights while that control is focused.
§Model
A label embeds a StaticText and delegates its geometry/id/flags to it; it
adds its own single-row draw and event handling. The link is an
Option<ViewId> — a resolvable handle, never a raw pointer. Focusing the
link is the Context::request_focus tree-op (the loop walks to the link’s
owning group and selects it); tracking the link’s focus state is a
broadcast subscription on its focus transitions.
§The highlight (light)
On a received/released-focus broadcast whose source is the link, the label
sets light to true (received) or false (released). Each focus transition of
the link emits a source == link focus broadcast, so the label’s highlight
follows the link’s focus. A broadcast about any other view (or with no link
set) leaves light unchanged.
Known limitation. This tracks focus changes, not link removal. Removing a child from a group nulls the group’s current selection without first emitting a release-focus on the departing child, so a label whose selectable link is removed at runtime can keep a stale highlight. No current code removes a bare link, so this does not bite in practice.
Marker decoration (the optional ^…^ highlight brackets) is not modeled — the
label always draws the plain form.
Broadcasts reach every child regardless of its event mask, so the label always sees focus broadcasts without any opt-in.
§Turbo Vision heritage
Ports TLabel (tlabel.cpp). Inheritance becomes an embed-and-delegate
wrapper over StaticText (deviation D2); the owner/link pointers become
Option<ViewId> with focusing routed through the event loop (deviations D3,
D4); the palette AttrPairs become explicit (lo, hi) Role pairs
((LabelNormal, LabelNormalShortcut) / (LabelLight, LabelLightShortcut)).
C++ TLabel paints an optional monochrome focus marker in column 0 when
showMarkers (SpecialChars) is set. tvision-rs does not model marker
decoration — a label always draws the plain form and the column-0 slot is
filler. Focus is shown by color (the label’s highlight role), which reads
correctly under both color and monochrome themes.
Implementations§
Source§impl Label
impl Label
Sourcepub fn new(bounds: Rect, text: impl Into<String>, link: Option<ViewId>) -> Self
pub fn new(bounds: Rect, text: impl Into<String>, link: Option<ViewId>) -> Self
Build a label over bounds with text (a ~-marked hotkey title)
optionally linking link.
Use this to attach a caption to a control inside a dialog. Mark the hotkey
character with tildes (e.g. "~N~ame" makes Alt+N — and on the
post-process walk, plain N — focus the linked control. Pass Some(id) to
connect the label to a control so it highlights when that control is focused;
pass None for a bare decorative caption with no focus behavior.
Passing None as the link is intentionally permitted — it creates a caption
that fires no focus request on click or hotkey. The C++ guide warns against a
nil link, but a bare caption is a valid and common use case in Rust dialogs.
Starts unlit and opts into both the pre-process and post-process event
phases (both load-bearing — a non-selectable label only ever sees its
hotkey via those sweeps). The fixed grow mode and non-selectable default
come from StaticText::new.
Sourcepub fn link(&self) -> Option<ViewId>
pub fn link(&self) -> Option<ViewId>
The control this label focuses on click or hotkey, if any.
Returns None when the label is a bare decorative caption — it still draws
and accepts hotkeys but click/hotkey clears the event without requesting
focus. A Some(id) handle is resolved by the event loop at focus time;
storing only the id means the label never holds a raw reference to its peer.
Sourcepub fn is_light(&self) -> bool
pub fn is_light(&self) -> bool
Whether the label is currently highlighted (its linked control holds focus).
Set to true when a RECEIVED_FOCUS broadcast arrives with
source == link, and back to false on RELEASED_FOCUS from the same
source. The draw path switches from the normal (LabelNormal, LabelNormalShortcut) role pair to (LabelLight, LabelLightShortcut) while
this is true. Stays false for a bare caption (link == None).
Trait Implementations§
Source§impl View for Label
impl View for Label
Source§fn draw(&mut self, ctx: &mut DrawCtx<'_>)
fn draw(&mut self, ctx: &mut DrawCtx<'_>)
Draw a single row: fill it with the caption color, then draw the
~-marked text at column 1 through put_cstr’s lo/hi
toggle (the ~ switches the highlighted shortcut character to the hi
role).
Source§fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)
fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context<'_>)
Handle the label’s events. Branches:
- MouseDown → focus the link and consume.
- KeyDown → if it is the Alt+hotkey accelerator (or, on the post-process walk only, the plain hotkey letter) → focus the link.
- Broadcast received/released-focus whose
sourceis our link → updatelight; not consumed (other views may also react).
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 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 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.menu::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 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.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 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 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 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.)Auto Trait Implementations§
impl Freeze for Label
impl RefUnwindSafe for Label
impl Send for Label
impl Sync for Label
impl Unpin for Label
impl UnsafeUnpin for Label
impl UnwindSafe for Label
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.