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:
MouseDownon an arrow does the first step, then callsContext::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.MouseUpclears tracking. -
Thumb drag:
MouseDownon the indicator (or outside the extent) does the first recompute, then arms the capture. Each tracked move recomputes the value from the thumb position.MouseUpclears tracking.
§Colors
Two Theme roles control the scrollbar appearance:
Role::ScrollBarPage— the trough (page) cells.Role::ScrollBarControls— arrow glyphs and the thumb.
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: ViewStateView state (geometry, flags, etc.) — the composition target.
value: i32Current 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: i32Inclusive 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: i32Inclusive 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: i32Distance 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: i32Distance 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
impl ScrollBar
Sourcepub fn new(bounds: Rect) -> Self
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.
Sourcepub fn with_keyboard(self) -> Self
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.
Sourcepub fn is_vertical(&self) -> bool
pub fn is_vertical(&self) -> bool
Whether this bar is oriented vertically (width == 1).
Sourcepub 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<'_>,
)
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.
Sourcepub fn set_value(&mut self, a_value: i32, ctx: &mut Context<'_>)
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.
Sourcepub fn set_range(&mut self, a_min: i32, a_max: i32, ctx: &mut Context<'_>)
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.
Sourcepub fn set_step(
&mut self,
a_pg_step: i32,
a_ar_step: i32,
ctx: &mut Context<'_>,
)
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.
Trait Implementations§
Source§impl View for ScrollBar
impl View for ScrollBar
Source§fn value(&self) -> Option<FieldValue>
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>
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<'_>)
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 source | Theme role |
|---|---|---|
| 0 | glyphs.sb_v_arrow_back | Role::ScrollBarControls |
| 1 .. pos-1 | glyphs.sb_page | Role::ScrollBarPage |
| pos | glyphs.sb_thumb | Role::ScrollBarControls |
| pos+1 .. s-1 | glyphs.sb_page | Role::ScrollBarPage |
| s | glyphs.sb_v_arrow_fwd | Role::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<'_>)
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 (viaset_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 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_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 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 ScrollBar
impl RefUnwindSafe for ScrollBar
impl Send for ScrollBar
impl Sync for ScrollBar
impl Unpin for ScrollBar
impl UnsafeUnpin for ScrollBar
impl UnwindSafe for ScrollBar
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.