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
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
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
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
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
Purpose
Scroll context or state structure.
Public fields
This type has no public fields.
See usage example
(&Scroll) offset
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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