pub struct Button {
pub state: ViewState,
pub title: String,
pub command: Command,
pub flags: ButtonFlags,
pub am_default: bool,
pub animation_timer: Option<TimerId>,
pub down: bool,
/* private fields */
}Expand description
A clickable command button: a 2+-row box with a centered (or
left-justified) title, a drop shadow, and an ~-marked hotkey. Pressing it
(mouse, Alt+hotkey, focused-Space, or — for the default button — the
Command::DEFAULT broadcast) fires its command, either
posted as an Event::Command or broadcast.
§Model
Button embeds ViewState and branches on its per-instance data; the
decoration/behavior flags are the ButtonFlags struct-of-bools. Drawing
goes through DrawCtx, events through Context. Coordinates are
view-local (the group already translated the mouse position into this view’s
frame).
§The press animation
A keyboard / Command::DEFAULT press does not fire immediately: it flips the button
to its pressed look (down = true), arms a one-shot 100 ms timer
(Context::set_timer), and stores the TimerId. When that timer’s
Event::Timer arrives (it reaches every view), the button compares the id
to its stored animation_timer; on a match it
clears the flash and finally presses. Matching the id
against the stored handle means a button only fires on its own timer, never
on an unrelated one.
Broadcast and timer events reach every child regardless of its event mask
(the mask only gates mouse_move/mouse_auto), so opting into the broadcast
class is automatic — no per-button state is needed.
§Mouse hold-tracking
A mouse-down inside the click rectangle begins a modal hold: the button sets
down = true and calls Context::start_mouse_track, caching the absolute
screen origin of button-local (0, 0) (recorded by the last draw) so the
capture can convert absolute mouse coordinates back to button-local.
From the next pump on, the
MouseTrackCapture routes every
MouseMove (localized to button-local) back into this handle_event: each
move flips down on tracking-rectangle containment. On MouseUp the button
presses iff the last move was still inside the tracking rectangle (self.down)
— never the release position — then clears down. Both arms are guarded by a
tracking flag so a stray, untracked release falls through. Every other event
during the hold is swallowed by the capture (the hold is modal). A button
without an id (an uninserted, test-only button) keeps a single-shot fallback.
§Command-enabled graying
When a Command::COMMAND_SET_CHANGED broadcast arrives, the button grays
itself out if its command is currently disabled
(state.disabled = !ctx.command_enabled(command)). Initial disabled state is
established the same way, by the first command-set-changed broadcast on the
opening idle pass — no separate constructor step is needed. A disabled default
button does not flash on the default-command broadcast.
§Plain-letter accelerator
When the button has its post-process option set, an unmodified letter that matches its hotkey fires it during the post-processing phase. A focused input line that consumes the letter first still starves this path, so plain letters are only stolen when the focused view leaves them live (matching Turbo Vision).
Marker decoration (showMarkers/specialChars) is not modeled — the button
always draws the no-markers form.
§Turbo Vision heritage
Ports TButton (tbutton.cpp/dialogs.h). Inheritance becomes the View
trait plus ViewState composition (deviation D2); the C++ button flag word
becomes ButtonFlags (deviation D5); the view-local grab/release-default
commands become namespaced Command::custom consts
(Button::GRAB_DEFAULT / Button::RELEASE_DEFAULT). The owner up-pointer
is replaced by Context, and a broadcast carries the firing button’s
resolvable ViewId as its source (deviations D3, D4). The palette
AttrPairs become explicit (lo, hi) Role pairs chosen per state (see
Button::state_roles); the typed Event::Timer(id) payload replaces the
C++ timer-expired broadcast.
Fields§
§state: ViewStateView state (geometry, flags, cursor) — the composition target.
title: StringThe button label displayed on the face. Surround a letter with ~ to
mark it as the hotkey: "~O~K" makes O the accelerator, drawn in the
shortcut (hi) color. The ~ characters themselves are not printed.
command: CommandThe command fired when the button is pressed. When the broadcast flag
is clear (the default), the command is posted as an Event::Command;
when the flag is set, it is broadcast with the button’s own
ViewId as the source.
flags: ButtonFlagsControls visual appearance and press behavior. Build with
ButtonFlags::new (all false) or struct-update syntax and flip
individual fields: ButtonFlags { default: true, ..ButtonFlags::new() }.
am_default: boolWhether the button is currently acting as the dialog’s default button —
that is, the one that fires when Command::DEFAULT (Enter) is pressed.
Starts as a copy of flags.default; toggled at runtime by
GRAB_DEFAULT / RELEASE_DEFAULT
broadcasts. Read this field to query the live default state; to change
it programmatically, send the appropriate broadcast or call
make_default.
animation_timer: Option<TimerId>The in-flight press-flash timer, if armed.
down: boolThe pressed appearance, read each redraw. true during the press flash.
Implementations§
Source§impl Button
impl Button
Sourcepub const GRAB_DEFAULT: Command
pub const GRAB_DEFAULT: Command
Sent by a focused non-default button to ask the current default button to relinquish the default look. A view-local, namespaced command.
Sourcepub const RELEASE_DEFAULT: Command
pub const RELEASE_DEFAULT: Command
The inverse of GRAB_DEFAULT: a non-default button
losing focus asks the default button to take the default look back.
Sourcepub fn new(
bounds: Rect,
title: &str,
command: Command,
flags: ButtonFlags,
) -> Self
pub fn new( bounds: Rect, title: &str, command: Command, flags: ButtonFlags, ) -> Self
Build a button from bounds, title, command, flags.
am_default follows the default flag; the press-flash timer starts
unarmed; the view is selectable and takes part in pre- and
post-processing.
Opting into the broadcast class is automatic (broadcasts reach every
child regardless of its event mask), so no per-button state is needed.
Initial command-enabled graying is established lazily by the first
command-set-changed broadcast rather than in the constructor; see the
Button docs.
Trait Implementations§
Source§impl View for Button
impl View for Button
Source§fn as_any_mut(&mut self) -> Option<&mut dyn Any>
fn as_any_mut(&mut self) -> Option<&mut dyn Any>
Exposes the concrete Button so the pump’s
MakeButtonDefault broker can
downcast a sibling button and call make_default.
Source§fn draw(&mut self, ctx: &mut DrawCtx<'_>)
fn draw(&mut self, ctx: &mut DrawCtx<'_>)
Paint the button, building each row explicitly so the shadow column and row land exactly.
Geometry: s = size.x - 1 (last column), t = size.y / 2 - 1 (the title
row). Body rows are y in 0..=size.y-2; the bottom row (size.y-1) is the
all-shadow stripe.
Normal (!down): each body row is filled with spaces in the button color,
col 0 gets the shadow style, and the right column s gets the shadow style
plus a shadow glyph (▄ on the top row, █ below). The title is drawn at
i+l with i = 1. The bottom row is 2 shadow spaces then ▀ across in the
shadow color.
Pressed (down): the body shifts right by one — cols 0..=1 take the shadow
style, the right-column shadow glyph vanishes (ch = ' '), the title is
drawn with i = 2. The bottom row is all shadow spaces.
§Note: DrawState merge
The C++ API exposes a separate DrawState(bool down) method called by both
Draw and HandleEvent. This port merges the two: the pressed/normal
distinction is captured in the self.down field, which draw reads
directly. There is no separate draw_state method.
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 button’s events — mouse hold-tracking, keyboard/hotkey presses,
default-look grab/release, and command-set graying. See the Button docs
for the per-branch behavior.
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<'_>)
Flip the propagating flag (replicating the trait-default body, since Rust
has no super for a default method) then, for StateFlag::Focused, run
make_default. No explicit redraw is needed on
select/activate (the whole tree is redrawn each pass).
Replicate-then-extend (the Group::set_state shape): flip the flag and, on
Focused, emit the base focus broadcast (Command::RECEIVED_FOCUS /
Command::RELEASED_FOCUS, source = self) — then make_default. So
focusing a non-default button queues RECEIVED_FOCUS then GRAB_DEFAULT.
Source§fn grabs_focus_on_click(&self) -> bool
fn grabs_focus_on_click(&self) -> bool
Opt-in for the mouse-down auto-select: only a button with the grab_focus
flag is selected (focused) by a click; the group consults this hook to
decide whether a click should focus the button.
Source§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 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 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 Button
impl RefUnwindSafe for Button
impl Send for Button
impl Sync for Button
impl Unpin for Button
impl UnsafeUnpin for Button
impl UnwindSafe for Button
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.