Guide API
Skip to main content

ScrollBar

Struct ScrollBar 

Source
pub struct ScrollBar {
    pub state: ViewState,
    pub value: i32,
    pub min_value: i32,
    pub max_value: i32,
    pub page_step: i32,
    pub arrow_step: i32,
    /* private fields */
}
Expand description

A single-axis scroll-bar widget: a draggable thumb between two step-arrows, with paging troughs on either side.

A scroll bar: a draggable thumb, paging troughs, and step arrows, drawn into its own 1×N (vertical) or N×1 (horizontal) bounds. Orientation is inferred from the bounds at construction: width == 1 means vertical, height == 1 means horizontal.

§Glyphs

The arrow/page/thumb characters live in crate::theme::Glyphs (sb_v_arrow_back, sb_v_arrow_fwd, sb_h_arrow_back, sb_h_arrow_fwd, sb_page, sb_thumb, sb_page_no_range) and are read via ctx.glyphs().

§Broadcasts

When the value changes, the bar broadcasts Command::SCROLL_BAR_CHANGED, carrying its own ViewId as the broadcast source, so an owner with two bars can tell which bar fired. On mouse-down / keyboard action it likewise broadcasts Command::SCROLL_BAR_CLICKED. The bar only emits these; a scroller, list viewer, or editor consumes them (see the scroller’s read-sync).

§Press-and-hold auto-repeat

The bar supports two modal holds, each driven through the mouse-track capture:

  • Arrow press-and-hold: MouseDown on an arrow does the first step, then calls Context::start_mouse_track. Each auto tick re-derives the part code under the cursor; if it still matches the clicked part, it steps the value. MouseUp clears tracking.

  • Thumb drag: MouseDown on the indicator (or outside the extent) does the first recompute, then arms the capture. Each tracked move recomputes the value from the thumb position. MouseUp clears tracking.

§Colors

Two Theme roles control the scrollbar appearance:

The classic blue theme resolves both to blue-on-cyan via the palette chain CScrollBar → cpBlueWindow → cpAppColor (slots 11–12 in the app palette). The C++ CScrollBar has three entries — page slot and two control slots (arrows + indicator); those two control slots share one RGB value, so Rust collapses them into the single ScrollBarControls role.

Orientation is derived from bounds at construction (size.x == 1 → vertical, size.y == 1 → horizontal). Construct with ScrollBar::new, then call set_params (or the convenience wrappers) to configure the range. When the user interacts with the bar it broadcasts Command::SCROLL_BAR_CHANGED; a paired scroller or list viewer listens for this broadcast and syncs its own position. The broadcast and press-and-hold protocol is described above.

§Turbo Vision heritage

Ports TScrollBar (tscrlbar.cpp/scrlbar.h). The hardcoded glyph tables become Glyphs fields (D7); the owner back-pointer plus its event payload become Context broadcasts that carry a resolvable ViewId source (D3, D4).

Fields§

§state: ViewState

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

§value: i32

Current scroll position within [min_value, max_value]. Starts at 0.

This field is readable but treat it as read-only from outside the widget: use set_value (or set_params) to change the position so the broker broadcast fires and the display stays consistent. The broker downcast path reads this field directly via View::value.

§min_value: i32

Inclusive lower bound of the scroll range. Starts at 0.

To update the range, call set_range or set_params — they clamp value and fire the Command::SCROLL_BAR_CHANGED broadcast.

§max_value: i32

Inclusive upper bound of the scroll range. Starts at 0.

To update the range, call set_range or set_params — they clamp value and fire the Command::SCROLL_BAR_CHANGED broadcast.

§page_step: i32

Distance the thumb moves when the user clicks the trough (page area). Starts at 1. To update both steps together, call set_step or set_params.

§arrow_step: i32

Distance the thumb moves when the user clicks an arrow or presses an arrow key. Starts at 1. To update both steps together, call set_step or set_params.

Implementations§

Source§

impl ScrollBar

Source

pub fn new(bounds: Rect) -> Self

Create a scrollbar sized to bounds.

Orientation is inferred at construction: bounds.size.x == 1 means vertical; bounds.size.y == 1 means horizontal. The grow mode is set accordingly so the bar stays pinned to its owner’s edge as the owner resizes.

All scroll state starts at zero (value, min_value, max_value) and both step sizes start at 1. Call set_params (or the convenience wrappers set_range / set_step) after inserting the bar into a group to configure the live range.

The bar is not selectable by default (no ofSelectable flag), which is intentional: mouse events are delivered directly by the group, and keyboard events reach it only through post-processing (enabled via with_keyboard).

Arrow/page glyph characters are read from DrawCtx::glyphs at draw time — they are not stored on the widget itself.

Source

pub fn with_keyboard(self) -> Self

Enable keyboard scrolling on this bar.

Sets the post-process option (ofPostProcess) so the bar receives arrow / page / Home / End keys from the focused chain even when the bar itself is not the current view. Use this when you want the keyboard to scroll a pane that has its own focused content (e.g. an editor with an attached vertical scrollbar).

Call this as a builder on new:

ⓘ
let bar = ScrollBar::new(bounds).with_keyboard();

Window::standard_scroll_bar passes handle_keyboard: true to achieve the same effect automatically.

Source

pub fn is_vertical(&self) -> bool

Whether this bar is oriented vertically (width == 1).

Source

pub fn set_params( &mut self, a_value: i32, a_min: i32, a_max: i32, a_pg_step: i32, a_ar_step: i32, ctx: &mut Context<'_>, )

Update value, range, and step sizes atomically.

a_max is floored to a_min; a_value is clamped to [a_min, a_max]. If value changed, broadcasts Command::SCROLL_BAR_CHANGED so that a linked scroller or list viewer can sync its own position (see the ScrollBar broadcast docs). Steps are set unconditionally at the end, regardless of whether the value or range changed.

The display is repainted automatically on the next whole-tree redraw pass — there is no explicit draw_view() call here (unlike the C++ TScrollBar::setParams, which called drawView() before broadcasting). The convenience wrappers set_value, set_range, and set_step all forward to this method.

Source

pub fn set_value(&mut self, a_value: i32, ctx: &mut Context<'_>)

Move the scroll position to a_value, clamped to [min_value, max_value].

Broadcasts Command::SCROLL_BAR_CHANGED if the value actually changes. Use this when the owner has scrolled programmatically and wants the bar to reflect the new position. Forwards to set_params.

Source

pub fn set_range(&mut self, a_min: i32, a_max: i32, ctx: &mut Context<'_>)

Update the [min, max] range, keeping value and step sizes.

value is clamped to the new range and, if it changed, a Command::SCROLL_BAR_CHANGED broadcast is emitted. Call this when the total size of the scrollable content changes (e.g. the file being edited gains or loses lines). Forwards to set_params.

Source

pub fn set_step( &mut self, a_pg_step: i32, a_ar_step: i32, ctx: &mut Context<'_>, )

Update the page and arrow step sizes, keeping value and range.

Changing step sizes does not broadcast — only a value change triggers Command::SCROLL_BAR_CHANGED. Use this when the visible area of the scrollable content changes (e.g. the window is resized), since the page size typically tracks the viewport height. Forwards to set_params.

Source

pub fn get_size(&self) -> i32

The scrollbar’s active length in cells: the axis length, at least 3.

Source

pub fn get_pos(&self) -> i32

The thumb position: a 1-based cell index along the bar’s axis (1..=get_size()-2 inclusive).

With an empty range the thumb sits at 1; otherwise the value is mapped linearly across the inner cells (get_size() - 3), rounded to nearest.

Trait Implementations§

Source§

impl View for ScrollBar

Source§

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

The bar’s value exposed as the typed transfer currency — a scroller, list viewer, or editor read-broker reads this through the trait (the pump resolves the bar by id and reads value).

Source§

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

Concrete-reach hatch (the sanctioned downcast): the pump downcasts to &mut ScrollBar to call set_params when applying a Deferred::ScrollBarSetParams from a scroller.

Source§

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

Paint the scrollbar into its one-cell-wide (or one-cell-tall) bounds.

The bar is divided into five logical zones (shown for vertical; horizontal mirrors on the x-axis):

Cell(s)Glyph sourceTheme role
0glyphs.sb_v_arrow_backRole::ScrollBarControls
1 .. pos-1glyphs.sb_pageRole::ScrollBarPage
posglyphs.sb_thumbRole::ScrollBarControls
pos+1 .. s-1glyphs.sb_pageRole::ScrollBarPage
sglyphs.sb_v_arrow_fwdRole::ScrollBarControls

When min_value == max_value (empty range), every inner cell is drawn with glyphs.sb_page_no_range and the thumb is omitted. Glyphs are read from DrawCtx::glyphs at paint time and are never stored on the widget. This replaces the C++ drawPos helper arrays and the hardcoded vChars/hChars tables.

Source§

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

Keyboard and mouse input.

Handles:

  • Mouse wheel: adjust by 3 * arrow_step, broadcasting clicked then changed (via set_value).
  • Mouse down: classify the part hit. Arrow parts do a first step and arm an auto-repeat track (TrackMask { mouse_auto: true }). The indicator/default branch does a first thumb-jump and arms a move track (TrackMask { mouse_move: true }). Broadcasts clicked.
  • Tracked auto tick: re-derive the part; step only if it still matches the originally-clicked part (the arrow/page hold loop body).
  • Tracked move: recompute the thumb value from the cursor position (the drag loop body).
  • Tracked mouse up: clear the tracking flag.
  • Key down (when visible + focused): arrow/page/home/end keys; broadcasts clicked then adjusts the value.
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 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 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.