Guide API
Skip to main content

Button

Struct Button 

Source
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: ViewState

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

§title: String

The 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: Command

The 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: ButtonFlags

Controls 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: bool

Whether 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: bool

The pressed appearance, read each redraw. true during the press flash.

Implementations§

Source§

impl Button

Source

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.

Source

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.

Source

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

Source§

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<'_>)

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<'_>)

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<'_>)

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

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