XU XUv0.13.1
中文

UI / WIDGETS / Layout

Scroll

Fit longer content inside a bounded viewport

Run the Xu example

The example executes in the browser using the Xu/WASM runtime.

What to try

Scroll the panel independently.

Usage notes

Content extent determines travel while the viewport determines clipping. Children inside scrolling content still need the correct parent and coordinates.

Create through Screen

The Screen constructor returns a node ID. Pass that ID to Screen layout, state and event APIs. It is separate from the standalone control object documented below.

Native Xu setup fragment: call configure during initialization of an existing Screen. See the complete example for window creation, event dispatch and cleanup.

#ui/widgets

fn configure(screen $&widgets.Screen) int {
    id := screen.scroll_area(widgets.AXIS_VERTICAL,600.0) or >>
    screen.place(id,24.0,24.0,320.0,80.0) or >>
    << id
}

($&Screen) scroll_area

XuAPI
pub fn (s $&Screen) scroll_area(axis int,content_extent f64) int

Purpose

Create Scroll in Screen and return the component node ID; throw on creation failure.

Parameters

s $&Screen
The Screen instance used by this call (exclusive borrow).
axis int
axis (int)
content_extent f64
content_extent (f64)

Returns

int — component node ID for place and other Screen methods.

Placement, state and events

The application owns the component. Screen.place positions nodes; Screen.set_enabled and Screen.set_visible control availability and visibility. Present again after state changes, handle or errors, and keep topology changes outside paint callbacks. ToastHost uses its own queue API.

Action · Styles · UI lifecycle and styling guide

Screen.place · Screen.set_enabled · Screen.set_visible

Standalone control object API

These types and methods support applications that manage control objects, input and painting directly. Their receiver is a control object, not a Screen node ID. For Screen usage, use the constructor above and the Screen methods in the Widgets module.

(&Scroll) clone

XuAPI
pub fn (value &Scroll) clone() Scroll

Purpose

Copy the control or style snapshot into an independent Scroll value.

Parameters

value &Scroll
The Scroll instance used by this call (borrow).

Returns

Scroll — a value of this type

(&Scroll) axis

XuAPI
pub fn (scroll &Scroll) axis() int

Purpose

Execute axis on &Scroll.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

int — a value of this type

(&Scroll) content_bounds

XuAPI
pub fn (scroll &Scroll) content_bounds() layout.Rect

Purpose

Children occupy content coordinates; the rail stays outside their clip.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

layout.Rect — a value of this type

struct Scroll

XuAPI
pub struct Scroll {

}

Purpose

Scroll context or state structure.

Public fields

This type has no public fields.

See usage example

(&Scroll) offset

XuAPI
pub fn (scroll &Scroll) offset() f64

Purpose

Execute offset on &Scroll.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

f64 — a value of this type

(&Scroll) needs_paint

XuAPI
pub fn (scroll &Scroll) needs_paint() bool

Purpose

Return whether the control needs repainting; call painted after painting to clear the flag.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

bool — true or false

($&Scroll) painted

XuAPI
pub fn (scroll $&Scroll) painted()

Purpose

Acknowledge the painted frame and clear the dirty flag; this is not a query.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&Scroll) set_focus

XuAPI
pub fn (scroll $&Scroll) set_focus(focused bool)

Purpose

Operation on $&Scroll: set focus.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
focused bool
focused (bool)

Returns

This call does not return a value.

($&Scroll) set_offset

XuAPI
pub fn (scroll $&Scroll) set_offset(offset f64) int

Purpose

Operation on $&Scroll: set offset. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
offset f64
offset (f64)

Returns

int — a value of this type

($&Scroll) set_content_extent

XuAPI
pub fn (scroll $&Scroll) set_content_extent(extent f64) int

Purpose

Operation on $&Scroll: set content extent. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
extent f64
extent (f64)

Returns

int — a value of this type

($&Scroll) set_bounds

XuAPI
pub fn (scroll $&Scroll) set_bounds(bounds &layout.Rect) int

Purpose

Operation on $&Scroll: set bounds. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
bounds &layout.Rect
bounds (read-only borrow; caller keeps the original; type &layout.Rect)

Returns

int — a value of this type

($&Scroll) input

XuAPI
pub fn (scroll $&Scroll) input(input &ui.InputEvent) Action

Purpose

Process routed mouse, keyboard, or touch input events. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
input &ui.InputEvent
input (read-only borrow; caller keeps the original; type &ui.InputEvent)

Returns

Action — input result with kind, id, repaint and focus requests.

($&Scroll) event

XuAPI
pub fn (scroll $&Scroll) event(event &ui.Event) Action

Purpose

Handle and respond to window or system lifecycle and interaction events. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
event &ui.Event
event (read-only borrow; caller keeps the original; type &ui.Event)

Returns

Action — input result with kind, id, repaint and focus requests.

(&Scroll) visible_items

XuAPI
pub fn (scroll &Scroll) visible_items(count int,item_extent f64,gap f64,overscan int) layout.VisibleRange

Purpose

Operation on &Scroll: visible items. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).
count int
count (int)
item_extent f64
item_extent (f64)
gap f64
gap (f64)
overscan int
overscan (int)

Returns

layout.VisibleRange — a value of this type

($&Scroll) layout_items

XuAPI
pub fn (scroll $&Scroll) layout_items(count int,item_extent f64,gap f64,overscan int) layout.VisibleRange

Purpose

Operation on $&Scroll: layout items. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
count int
count (int)
item_extent f64
item_extent (f64)
gap f64
gap (f64)
overscan int
overscan (int)

Returns

layout.VisibleRange — a value of this type

(&Scroll) begin

XuAPI
pub fn (scroll &Scroll) begin(frame $&draw.Frame) int

Purpose

Execute begin on &Scroll. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)

Returns

int — a value of this type

(&Scroll) end

XuAPI
pub fn (scroll &Scroll) end(frame $&draw.Frame) int

Purpose

Execute end on &Scroll. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)

Returns

int — a value of this type

(&Scroll) is_enabled

XuAPI
pub fn (scroll &Scroll) is_enabled() bool

Purpose

Return whether the control is currently enabled.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

bool — true or false

($&Scroll) set_enabled

XuAPI
pub fn (scroll $&Scroll) set_enabled(enabled bool)

Purpose

Operation on $&Scroll: set enabled.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
enabled bool
enabled (bool)

Returns

This call does not return a value.

(&Scroll) id

XuAPI
pub fn (scroll &Scroll) id() int

Purpose

Return the unique integer ID of the element or control.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

int — a value of this type

(&Scroll) bounds

XuAPI
pub fn (scroll &Scroll) bounds() layout.Rect

Purpose

Return the bounding Rectangle of the control or geometry.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Scroll) is_focused

XuAPI
pub fn (scroll &Scroll) is_focused() bool

Purpose

Return whether the control currently has input focus.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

bool — true or false

(&Scroll) is_hovered

XuAPI
pub fn (scroll &Scroll) is_hovered() bool

Purpose

Operation on &Scroll: whether it is hovered.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

bool — true or false

(&Scroll) is_dragging

XuAPI
pub fn (scroll &Scroll) is_dragging() bool

Purpose

Operation on &Scroll: whether it is dragging.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

bool — true or false

(&Scroll) is_invalid

XuAPI
pub fn (scroll &Scroll) is_invalid() bool

Purpose

Operation on &Scroll: whether it is invalid.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

bool — true or false

($&Scroll) set_invalid

XuAPI
pub fn (scroll $&Scroll) set_invalid(invalid bool)

Purpose

Operation on $&Scroll: set invalid.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
invalid bool
invalid (bool)

Returns

This call does not return a value.

(&Scroll) visual_state

XuAPI
pub fn (scroll &Scroll) visual_state() int

Purpose

Operation on &Scroll: visual state.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

int — a value of this type

(&Scroll) has_style

XuAPI
pub fn (scroll &Scroll) has_style() bool

Purpose

Operation on &Scroll: whether it has style.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

bool — true or false

(&Scroll) style_or

XuAPI
pub fn (scroll &Scroll) style_or(styles &Styles) ControlStyle

Purpose

Operation on &Scroll: style or.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

ControlStyle — a value of this type

($&Scroll) set_style

XuAPI
pub fn (scroll $&Scroll) set_style(style &ControlStyle) int

Purpose

Operation on $&Scroll: set style. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
style &ControlStyle
style (read-only borrow; caller keeps the original; type &ControlStyle)

Returns

int — a value of this type

($&Scroll) clear_style

XuAPI
pub fn (scroll $&Scroll) clear_style()

Purpose

Operation on $&Scroll: clear style.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&Scroll) apply_styles

XuAPI
pub fn (scroll $&Scroll) apply_styles(styles &Styles) int

Purpose

Validate and apply styles, updating layout / geometry and repainting when metrics change.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

0 on success; throws on failure

($&Scroll) measure_styled

XuAPI
pub fn (scroll $&Scroll) measure_styled(styles &Styles) layout.Size

Purpose

Operation on $&Scroll: measure styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

layout.Size — a value of this type

(&Scroll) scrollbar_track

XuAPI
pub fn (scroll &Scroll) scrollbar_track() layout.Rect

Purpose

Return the scrollbar track rectangle shared with hit testing.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

track in control coordinates

(&Scroll) scrollbar_thumb

XuAPI
pub fn (scroll &Scroll) scrollbar_thumb() layout.Rect

Purpose

Return the thumb rectangle from content extent, offset and minimum thumb size.

Parameters

scroll &Scroll
The Scroll instance used by this call (borrow).

Returns

thumb in control coordinates

($&Scroll) paint_scrollbar

XuAPI
pub fn (scroll $&Scroll) paint_scrollbar(frame $&draw.Frame,styles &Styles) int

Purpose

Paint the scrollbar and clear its dirty flag. Call after child content in overlay_styled.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

0 on success; throws on failure

($&Scroll) route

XuAPI
pub fn (scroll $&Scroll) route(kind int,input &ui.InputEvent) Action

Purpose

Route and dispatch the input event to matching targets. Throws on failure; handle the error or propagate it to the caller.

Parameters

scroll $&Scroll
The Scroll instance used by this call (exclusive borrow).
kind int
kind tag (int)
input &ui.InputEvent
input (read-only borrow; caller keeps the original; type &ui.InputEvent)

Returns

Action — input result with kind, id, repaint and focus requests.

Complete native example

Component Workshop · Back to Widgets