scrollview

package
v0.1.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 1, 2026 License: MIT Imports: 5 Imported by: 1

Documentation

Overview

Package scrollview provides a scrollable container widget for clipping and navigating content that exceeds the viewport size.

Construction uses functional options for immutable configuration: 

sv := scrollview.New(content,
    scrollview.DirectionOpt(scrollview.Vertical),
    scrollview.ScrollbarOpt(scrollview.ScrollbarAuto),
    scrollview.OnScroll(handleScroll),
)

Scroll Direction

Three directions are available:

  • Vertical (default) -- content scrolls up/down
  • Horizontal -- content scrolls left/right
  • Both -- content scrolls in both directions

Scrollbar Visibility

Scrollbar display is controlled by ScrollbarVisibility:

Visual Style

The scrollbar rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) supplies its own painter to render scrollbars in the appropriate visual style.

If no painter is set, DefaultPainter is used, which draws minimal scrollbars suitable for testing and prototyping.

Interaction

ScrollView responds to:

  • Mouse wheel for vertical/horizontal scrolling
  • Mouse drag on scrollbar thumb to scroll
  • Keyboard: Up/Down arrows for small steps, Page Up/Page Down for viewport-sized steps, Home/End to scroll to top/bottom

Signal Binding

Scroll positions can be bound to reactive signals from the state package. When a signal value changes, the scroll position automatically reflects the new state:

Example: 

scrollY := state.NewSignal[float32](0)
sv := scrollview.New(content,
    scrollview.ScrollYSignal(scrollY),
    scrollview.OnScroll(func(x, y float32) {
        fmt.Printf("scroll: %.0f, %.0f\n", x, y)
    }),
)

Focus

ScrollView implements widget.Focusable and participates in tab navigation. When focused, keyboard navigation is available.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DefaultPainter 

type DefaultPainter struct{}

DefaultPainter provides a minimal fallback painter with no design system styling. It draws simple scrollbars -- useful for testing and as a base reference.

func (DefaultPainter) PaintScrollbar 

func (p DefaultPainter) PaintScrollbar(canvas widget.Canvas, ps PaintState)

PaintScrollbar renders minimal scrollbars with gray track and darker thumb.

type Option 

type Option func(*config)

Option configures a scroll view during construction.

func DirectionOpt 

func DirectionOpt(d ScrollDirection) Option

DirectionOpt sets the scroll direction. Default is Vertical.

func OnScroll 

func OnScroll(fn func(x, y float32)) Option

OnScroll sets the callback invoked when the scroll position changes. The callback receives the new (scrollX, scrollY) offsets.

func PainterOpt 

func PainterOpt(p Painter) Option

PainterOpt sets the painter used to render the scrollbar. Each design system provides its own painter. If not set, DefaultPainter is used.

func ScrollStep 

func ScrollStep(step float32) Option

ScrollStep sets the number of pixels scrolled per wheel tick. Default is 40 pixels.

func ScrollX 

func ScrollX(x float32) Option

ScrollX sets the initial horizontal scroll offset.

func ScrollXReadonlySignal 

func ScrollXReadonlySignal(sig state.ReadonlySignal[float32]) Option

ScrollXReadonlySignal binds the horizontal scroll offset to a read-only signal. When set, this takes highest precedence over all other scrollX sources.

func ScrollXSignal 

func ScrollXSignal(sig state.Signal[float32]) Option

ScrollXSignal binds the horizontal scroll offset to a reactive signal. This is a TWO-WAY binding: the widget reads the offset from the signal, and when the user scrolls, the new offset is written back to the signal.

func ScrollY 

func ScrollY(y float32) Option

ScrollY sets the initial vertical scroll offset.

func ScrollYReadonlySignal 

func ScrollYReadonlySignal(sig state.ReadonlySignal[float32]) Option

ScrollYReadonlySignal binds the vertical scroll offset to a read-only signal. When set, this takes highest precedence over all other scrollY sources.

func ScrollYSignal 

func ScrollYSignal(sig state.Signal[float32]) Option

ScrollYSignal binds the vertical scroll offset to a reactive signal. This is a TWO-WAY binding: the widget reads the offset from the signal, and when the user scrolls, the new offset is written back to the signal.

func ScrollbarOpt 

func ScrollbarOpt(v ScrollbarVisibility) Option

ScrollbarOpt sets the scrollbar visibility mode. Default is ScrollbarAuto.

type PaintState 

type PaintState struct {
	Bounds      geometry.Rect // total widget bounds (viewport)
	Direction   ScrollDirection
	Focused     bool
	Hovered     bool
	Dragging    bool
	ColorScheme ScrollbarColorScheme

	// Vertical scrollbar state.
	VScrollVisible bool          // whether vertical scrollbar should be drawn
	VThumbRect     geometry.Rect // vertical thumb rectangle
	VTrackRect     geometry.Rect // vertical track rectangle

	// Horizontal scrollbar state.
	HScrollVisible bool          // whether horizontal scrollbar should be drawn
	HThumbRect     geometry.Rect // horizontal thumb rectangle
	HTrackRect     geometry.Rect // horizontal track rectangle
}

PaintState provides the current scrollbar state to the painter.

type Painter 

type Painter interface {
	PaintScrollbar(canvas widget.Canvas, state PaintState)
}

Painter draws the visual representation of scrollbars. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render scrollbars in its visual style.

If no Painter is set, the scroll view uses DefaultPainter.

type ScrollDirection 

type ScrollDirection uint8

ScrollDirection controls which axes the scroll view scrolls along. 

const (
	// Vertical enables vertical scrolling only. This is the default.
	Vertical ScrollDirection = iota

	// Horizontal enables horizontal scrolling only.
	Horizontal

	// Both enables scrolling on both axes.
	Both
)

ScrollDirection constants.

func (ScrollDirection) String 

func (d ScrollDirection) String() string

String returns a human-readable name for the scroll direction.

type ScrollbarColorScheme 

type ScrollbarColorScheme struct {
	Track      widget.Color // scrollbar track background
	Thumb      widget.Color // scrollbar thumb fill
	ThumbHover widget.Color // scrollbar thumb fill when hovered
	ThumbDrag  widget.Color // scrollbar thumb fill when dragging
}

ScrollbarColorScheme provides theme-derived colors for scrollbar painting. Zero value means the painter should use its built-in defaults.

type ScrollbarVisibility 

type ScrollbarVisibility uint8

ScrollbarVisibility controls when scrollbars are displayed. 

const (
	// ScrollbarAuto shows scrollbars only when content overflows. This is the default.
	ScrollbarAuto ScrollbarVisibility = iota

	// ScrollbarAlways shows scrollbars regardless of content size.
	ScrollbarAlways

	// ScrollbarNever hides scrollbars completely.
	ScrollbarNever
)

ScrollbarVisibility constants.

func (ScrollbarVisibility) String 

func (v ScrollbarVisibility) String() string

String returns a human-readable name for the scrollbar visibility mode.

type Widget 

type Widget struct {
	widget.WidgetBase
	// contains filtered or unexported fields
}

Widget implements a scrollable container that clips and translates its content child widget.

A scroll view is created with New using functional options: 

sv := scrollview.New(content,
    scrollview.DirectionOpt(scrollview.Vertical),
    scrollview.OnScroll(handleScroll),
)

func New 

func New(content widget.Widget, opts ...Option) *Widget

New creates a new scroll view Widget wrapping the given content widget.

The returned widget is visible, enabled, and focusable by default. The default direction is Vertical with ScrollbarAuto visibility.

func (*Widget) Children 

func (w *Widget) Children() []widget.Widget

Children returns the content widget as the single child.

func (*Widget) Content 

func (w *Widget) Content() widget.Widget

Content returns the scroll view's content widget.

func (*Widget) ContentSize 

func (w *Widget) ContentSize() geometry.Size

ContentSize returns the measured content size.

func (*Widget) Draw 

func (w *Widget) Draw(ctx widget.Context, canvas widget.Canvas)

Draw renders the scroll view to the canvas.

Drawing order:

  1. Push clip to viewport bounds
  2. Push transform for scroll offset
  3. Draw content
  4. Pop transform
  5. Pop clip
  6. Draw scrollbar(s) on top

func (*Widget) Event 

func (w *Widget) Event(ctx widget.Context, e event.Event) bool

Event handles an input event and returns true if consumed.

Event coordinates are transformed from parent space to content space before dispatching to the content widget. This is the inverse of the Draw transform (PushTransform with scroll offset), following the universal GUI framework pattern used by Flutter, Qt, WPF, and Gio.

Scrollbar interactions are NOT transformed because scrollbars are drawn on top of the viewport in parent-space coordinates.

func (*Widget) IsFocusable 

func (w *Widget) IsFocusable() bool

IsFocusable reports whether the scroll view can currently receive focus.

func (*Widget) Layout 

func (w *Widget) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size

Layout calculates the scroll view's size and measures its content.

The viewport is constrained to the parent's constraints. The content is measured with unconstrained dimensions along the scroll axis to determine its natural size.

func (*Widget) Mount 

func (w *Widget) Mount(ctx widget.Context)

Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.

func (*Widget) Padding 

func (w *Widget) Padding(_ float32) *Widget

Padding sets the content padding. Returns the widget for method chaining.

func (*Widget) ScrollOffset 

func (w *Widget) ScrollOffset() (x, y float32)

ScrollOffset returns the current scroll offset.

func (*Widget) ScrollbarInset 

func (w *Widget) ScrollbarInset() float32

ScrollbarInset returns the width reserved for visible scrollbars. When the vertical scrollbar is shown, this is the total scrollbar width (track + padding). Otherwise zero.

func (*Widget) Unmount 

func (w *Widget) Unmount()

Unmount is called when the scroll view is removed from the widget tree. Implements widget.Lifecycle.

func (*Widget) ViewportSize 

func (w *Widget) ViewportSize() geometry.Size

ViewportSize returns the current viewport size.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.