Guide API
Skip to main content

Scroller

Struct Scroller 

Source
pub struct Scroller {
    pub delta: Point,
    /* private fields */
}
Expand description

The base scrollable-content view.

The base for scrollable content views (the editor, the text terminal, the outline viewer). A scroller references two sibling scroll bars that live on the window frame, mirrors their value into its own delta (the scroll offset its subclasses draw with), and pushes range/value changes back to them.

§The cross-view scrollbar broker — read and write

A scroller both reads its two scroll bars (their value, arrow step) and mutates them (set value/params, show/hide). But a leaf view holds only &mut Context during dispatch — no tree access — and the bars are window-frame siblings it cannot own, so it can neither read nor mutate them directly.

The event loop is the broker, in both directions. The scroller stores its bars as Option<ViewId> handles and issues Deferred ops naming them; the loop performs every cross-view read/write at apply time. A SCROLL_BAR_CHANGED broadcast’s source is the filter only (the scroller reacts iff source ∈ {h, v}); the value is not stuffed into the message — the loop resolves the subject bar and reads its value.

§Selected color

The base scroller only ever draws a fill in Role::ScrollerNormal. The “selected” scroller color exists in the palette but is never used by the base; the editor, which selects text, applies its own selection color, so no ScrollerSelected role is wired here.

§Resizing

View::change_bounds takes no Context, but re-publishing scroll-bar parameters after a resize needs one. So change_bounds stays geometry-only, and Scroller::set_limit / Scroller::scroll_to are the public Context-taking entries that (re)publish the parameters; a window or editor that resizes a scroller calls set_limit afterwards. There is no automatic re-emit on a bare bounds change, because nothing currently drives that path.

Manages scroll state and keeps two sibling scroll bars in sync with its content offset. The base draws only a uniform fill; subclasses (e.g. the editor) override draw and use delta to shift their content. Wire a Scroller into a window by passing the scroll bar ViewIds at construction time; call set_limit whenever the content size changes, and scroll_to to jump to a position programmatically.

Cross-view scroll-bar reads and writes are brokered by the event loop, as described above.

§Turbo Vision heritage

Ports TScroller (tscrolle.cpp). Owner back-pointers to the sibling scroll bars become ViewId handles brokered by the event loop, and the palette becomes Roles. The original draw-re-entrancy guard is unneeded under whole-tree redraw and is dropped.

Fields§

§delta: Point

The current scroll offset, mirrored from the scroll bars.

Updated by the event loop (via apply_delta) whenever a scroll bar’s value changes. Subclasses read this in their draw override to shift content: a line at logical row r is rendered at screen row r - delta.y, and similarly for x. Do not write delta directly; use scroll_to to request a position change.

Implementations§

Source§

impl Scroller

Source

pub fn new( bounds: Rect, h_scroll_bar: Option<ViewId>, v_scroll_bar: Option<ViewId>, ) -> Self

Create a scroller with the given bounds and optional scroll bar handles.

Pass the ViewIds of the horizontal and vertical scroll bars, or None for either axis you don’t need. The scroller starts at offset (0, 0) with an empty content extent; call set_limit after construction to publish the initial range to the bars. The view is marked selectable so it can receive keyboard focus.

Broadcasts are delivered unconditionally — there is no broadcast event mask bit — so no extra setup is needed to receive SCROLL_BAR_CHANGED.

Source

pub fn limit(&self) -> Point

Return the current content extent as set by set_limit.

The returned point (x, y) is the logical width and height of the scrollable content. Use this in a subclass draw implementation if you need to know the total content size independently of delta. To change the extent, call set_limit — it both stores the value and re-publishes the range to the scroll bars.

Source

pub fn h_scroll_bar(&self) -> Option<ViewId>

Return the ViewId of the horizontal scroll bar, if one was supplied.

Use this in a subclass when you need to address the scroll bar directly (e.g. to call scroll_to or query the bar’s ViewId for a broker operation). Returns None if the scroller was created without a horizontal bar.

§Turbo Vision heritage

Corresponds to the public TScroller::hScrollBar pointer. In Rust the raw pointer becomes a ViewId handle; the event loop brokers all cross-view reads and writes through it rather than allowing direct pointer access.

Source

pub fn v_scroll_bar(&self) -> Option<ViewId>

Return the ViewId of the vertical scroll bar, if one was supplied.

Use this in a subclass when you need to address the scroll bar directly. Returns None if the scroller was created without a vertical bar.

§Turbo Vision heritage

Corresponds to the public TScroller::vScrollBar pointer. See h_scroll_bar for the broker rationale.

Source

pub fn apply_delta(&mut self, d: Point)

Apply a freshly-resolved scroll offset from the event loop’s read broker.

This is the Rust analog of C++ TScroller::scrollDraw. It is called by the pump after it resolves both scroll bars and reads their current values, assembling them into d. If d differs from the stored delta, the cursor is shifted by old_delta - d (using the old value — order matters) and then delta is overwritten. The whole-tree redraw that follows the pump tick replaces the C++ drawView call.

Do not call this directly. It is public so the pump can reach it via the as_any_mut downcast; call scroll_to to request a position change from user code.

§Turbo Vision heritage

Ports TScroller::scrollDraw. The original read the bar values directly via raw pointers; here the pump reads them and passes the result in d.

Source

pub fn set_limit(&mut self, x: i32, y: i32, ctx: &mut Context<'_>)

Set the content extent to (x, y) and re-publish each bar’s range and page parameters.

Call this after construction and after any resize to tell the scroll bars the total content dimensions. For the horizontal bar: min = 0, max = x - view_width, page_step = view_width - 1; the vertical bar mirrors on y and view_height. The current bar value and arrow step are preserved. Cross-view writes are queued as deferred ScrollBarSetParams ops executed by the pump — no direct bar access occurs.

on_bounds_changed calls set_limit automatically after a resize with the previously stored extent, so you only need to call it explicitly when the content size changes.

Source

pub fn scroll_to(&mut self, x: i32, y: i32, ctx: &mut Context<'_>)

Request that the scroll bars move to position (x, y), preserving range and steps.

Queues a deferred ScrollBarSetParams op for each present bar with only value updated (the range, page step, and arrow step are left unchanged). The bar clamps the value to its live range at apply time. The resulting SCROLL_BAR_CHANGED broadcast will then trigger the read broker, which calls apply_delta to update delta.

Call this to programmatically jump to a position, e.g. “go to line N” in an editor. If you only need to update the bar’s range (e.g. after loading new content), use set_limit instead.

Trait Implementations§

Source§

impl View for Scroller

Source§

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

A uniform fill of the entire view rect with Role::ScrollerNormal (no active/selected branch). The “selected” scroller color is never used by the base; the editor applies its own selection color instead.

Subclasses (the editor) override draw and consume delta.

Source§

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

React to a SCROLL_BAR_CHANGED broadcast whose source is one of this scroller’s two bars by requesting a deferred delta-sync (the read broker; see the Scroller docs).

The source ∈ {h_id, v_id} test is the filter that decides whether this scroller owns the firing bar.

Source§

fn apply_scroll_sync( &mut self, h: Option<i32>, v: Option<i32>, _ctx: &mut Context<'_>, )

Called by the pump after it reads the sibling scrollbar values. Applies the resulting delta to this scroller. A missing bar (None) is treated as delta 0 — faithful to the previous .unwrap_or(0) read in the old pump arm.

Source§

fn set_state(&mut self, flag: StateFlag, enable: bool, ctx: &mut Context<'_>)

Flip a state flag and show or hide the scroll bars when focus changes.

After updating the flag, if flag is Active or Selected, each scroll bar is shown when either flag is set and hidden when both are clear. This matches the C++ behaviour: bars are visible whenever the scroller (or one of its ancestors) has input focus. Visibility is applied via a deferred SetVisible op brokered by the pump, not by a direct call into the bar.

When flag is Focused, the standard RECEIVED_FOCUS / RELEASED_FOCUS broadcast is emitted; no bar visibility change occurs.

Source§

fn on_bounds_changed(&mut self, ctx: &mut Context<'_>)

Re-publish scroll bar range parameters after a bounds change.

Called by the pump after it has applied a Deferred::ChangeBounds op, so self.size already reflects the new dimensions. Calls set_limit with the previously stored limit values so the bars’ max and page_step are recomputed for the new view size.

Subclasses that override this should call super.on_bounds_changed(ctx) (or call set_limit themselves) to keep the bars consistent.

Source§

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

Concrete-reach hatch (the sanctioned downcast): retained as a generic escape so Terminal can delegate as_any_mut to its inner Scroller. The Deferred::ScrollSync arm does NOT use this hatch — it dispatches apply_scroll_sync to the Scroller override through the View trait (delegate forwarder), not via as_any_mut.

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