Scroll

Containers · container · interactive

A scroll container.

Import

#include "gbui/widgets/scroll.hpp"

Example

ScrollArea

scrollArea · Containers · container · interactive

Nothing is downloaded until you press it.

Ui::Scope scrollArea(Ui& ui, const Interaction& input, std::string_view id, ScrollState& state, const ScrollOptions& options = {});

Opens a scroll container. The content is laid out at its natural size and clipped to the viewport, and the offset moves it. Wheel over the container scrolls it; Page Up, Page Down, Home and End do too when it has focus; the bar can be dragged. Everything drawn inside costs a node, so this is a scrolling view and not a virtualised one — 50 000 rows here really do build 50 000 nodes. When the rows are uniform, virtualList builds only the visible ones — see virtualList.hpp.

Scrollbar

scrollbar · Containers · interactive

Nothing is downloaded until you press it.

void scrollbar(Ui& ui, const Interaction& input, std::string_view id, const ScrollState& state, Rect box, ScrollAxis axis = ScrollAxis::Vertical, float width = 10.0f, bool autoHide = true, float opacity = 1.0f);

Draws the bar for a scroll view that is not where the bar belongs. A bar normally lives inside the view it drives, and scrollArea puts it there. A table is the case that forced this one out: its rows scroll vertically inside a box that scrolls horizontally, so the row view's own right-hand edge is out at the end of the widest column, and the bar drawn against it is a bar the reader has to scroll sideways to find. A browser has no such problem, because both bars belong to the visible box; this is how a caller says the same thing here. box is in the current container's coordinates — where the bar should be, not where the content is. The ids are the view's own, so the press, the drag and the paging are still handled by scrollArea: this draws, it does not behave. Turn the view's own bar off with ScrollOptions::scrollbar when you use it, or there will be two.

API

ScrollOptions

Option	Type	Default	What it does
direction	Direction	Direction::Column
axis optional	std::optional<ScrollAxis> None · Vertical · Horizontal		Which way it scrolls. Auto follows direction, which is what a column of rows or a row of chips almost always wants.
step	float	48.0f	Pixels per wheel notch.
scrollbar	bool	true	Draws the bar. Turning it off leaves wheel and keyboard scrolling.
scrollbarWidth	float	10.0f
autoHideScrollbar	bool	true	Hides the bar when the content fits, the way a desktop does. This is about there being nothing to scroll — see scrollbarVisibility for the bar that fades while there is.
scrollbarVisibility	ScrollbarVisibility Always · WhileUsed	ScrollbarVisibility::Always	Whether the bar is always there or only while the view is being used.
scrollbarRestOpacity	float	0.0f	What WhileUsed fades to, 0 to 1. Zero is SimpleBar's answer and takes the bar away entirely. A small number — 0.2 or so — is usually the better one: it keeps the position indicator, which is half of what a bar is for, and still gets out of the way of the content.
scrollbarFadeDelay	float	0.8f	How long the bar stays after the pointer leaves, in seconds. Short enough not to linger, long enough that crossing the view on the way to something else does not leave a bar flashing behind.
focusable	bool	true	Whether Tab can land on the viewport. A pane the reader scrolls for itself wants that; a list inside a control that already holds the keyboard — a select — does not, or Tab walks into the popup.
padding	Edges
gap	float	0.0f
grow	float	1.0f
width	float	kAuto
height	float	kAuto
minWidth	float	kAuto	Bounds on the viewport itself. A maximum is what turns "as tall as its content" into "as tall as its content, then scroll" — which is the rule a dropdown needs and could not express before.
maxWidth	float	kAuto
minHeight	float	kAuto
maxHeight	float	kAuto
name	std::string_view		What the region is, for a reader who cannot see a scrollbar. Only used when focusable, since that is the only time the region is a place the keyboard can be.