Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

The AG_Scrollbar widget allows the user to control an integer or floating-point value within a specified range. AG_Scrollbar is almost always used from a widget implementation, to provide scrolling controls (and it features a special visible binding to faciliate this application).

For example, in a scrollable view containing a given number of "items" (e.g., the lines of a multi-line AG_Textbox(3)), the max binding would be tied to the total item count, and the visible binding would be tied to the number of items that can be displayed on-screen (based on the current widget dimensions). Finally, the value binding is tied to an index variable defining the first item that should be rendered.

NOTE: For general-purpose edition of numerical values, AG_Slider(3) or AG_Numerical(3) are more suitable widgets.

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Widget(3)-> AG_Scrollbar.

INTERFACE

AG_Scrollbar * AG_ScrollbarNew (AG_Widget *parent, enum ag_scrollbar_type type, Uint flags)

AG_Scrollbar * Fn AG_ScrollbarNew{Int,Uint,Float,Double} "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "<Type> *val" "<Type> *min" "<Type> *max" "<Type> *visible"
AG_Scrollbar * Fn AG_ScrollbarNew{Uint8,Uint16,Uint32} "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "<Type> *val" "<Type> *min" "<Type> *max" "<Type> *visible"
AG_Scrollbar * Fn AG_ScrollbarNew{Sint8,Sint16,Sint32} "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "<Type> *val" "<Type> *min" "<Type> *max" "<Type> *visible"
void AG_ScrollbarSizeHint (AG_Scrollbar *scrollbar, int length)

void AG_ScrollbarSetControlLength (AG_Scrollbar *scrollbar, int length)

int AG_ScrollbarControlLength (AG_Scrollbar *scrollbar)

void AG_ScrollbarSetWidth (int width)

int AG_ScrollbarWidth (void)

void AG_ScrollbarSetPrefWidth (int width)

int AG_ScrollbarPrefWidth (void)

int AG_ScrollbarVisible (AG_Scrollbar *scrollbar)

void AG_ScrollbarSetIncFn (AG_Scrollbar *scrollbar, AG_EventFn fn, const char *fmt, ...)

void AG_ScrollbarSetDecFn (AG_Scrollbar *scrollbar, AG_EventFn fn, const char *fmt, ...)

void AG_ScrollbarSetIntIncrement (AG_Scrollbar *scrollbar, int increment)

void AG_ScrollbarSetRealIncrement (AG_Scrollbar *scrollbar, double increment)

The AG_ScrollbarNew() function allocates, initializes, and attaches a new AG_Scrollbar widget. The type argument should be either AG_SCROLLBAR_HORIZ or AG_SCROLLBAR_VERT. Acceptable flags include:

AG_SCROLLBAR_AUTOSIZE	Automatically determine the size of the scrollbar control based on current `min`, `max` and `visible` values (recommended).
AG_SCROLLBAR_AUTOHIDE	Automatically hide or show the scrollbar based on the usefulness of the current numerical range.
AG_SCROLLBAR_HFILL	Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)). This flag is only sensible with horizontal scrollbars, and renders the use of AG_ScrollbarSizeHint() unnecessary.
AG_SCROLLBAR_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)). This flag is only sensible with vertical scrollbars, and renders the use of AG_ScrollbarSizeHint() unnecessary.
AG_SCROLLBAR_EXPAND	Shorthand for AG_SCROLLBAR_HFILL\|AG_SCROLLBAR_VFILL.
AG_SCROLLBAR_TEXT	Display the minimum, current and maximum values in text. This option is primarily useful for debugging.

Alternate constructor routines Fn AG_ScrollbarNew{Int,Uint,Float,Double} ,Fn AG_ScrollbarNew{Uint8,Uint16,Uint32}and Fn AG_ScrollbarNew{Sint8,Sint16,Sint32}create a new AG_Scrollbar with value, min, max, and visible bound to the variables of the specified integer or floating-point type.

AG_ScrollbarSizeHint() specifies a default, preferred scrollbar length in pixels. It is not necessary to invoke this function when using the AG_SCROLLBAR_HFILL or AG_SCROLLBAR_VFILL flag.

The AG_ScrollbarSetControlLength() function sets the length of the scrolling control (i.e., the center button), in pixels. This length is often computed from the ratio between the visible area of whatever is being displayed, and the total area of the content that can be displayed. AG_ScrollbarControlLength() returns the current length of the scrolling control, in pixels.

AG_ScrollbarSetWidth() configures the width (i.e., thickness) of the scrollbar. AG_ScrollbarWidth() returns the effective width of a scrollbar in pixels.

If the width of the scrollbar is not specified on initialization, AG_Scrollbar will use a default width. This default width can be set with AG_ScrollbarSetPrefWidth(), and retrieved with AG_ScrollbarPrefWidth() (typically from the size_request() or size_allocate() operation of a container widget).

Note: Under multithreading, AG_ScrollbarControlLength(), AG_ScrollbarWidth() and AG_ScrollbarPrefWidth() should be considered safe to invoke only in widget context (e.g., event handlers, size_request(), size_allocate() or draw() operations)

The AG_ScrollbarVisible() function returns 1 if the current range is such that the scrollbar is useful to display, otherwise it returns 0.

The AG_ScrollbarSetDecFn() and AG_ScrollbarSetIncFn() functions configure a callback routine that will be invoked when the user presses the decrement (up/left) button and the increment (down/right) buttons. A single int argument is passed to the callback (1 = pressed, 0 = released).

AG_ScrollbarSetIntIncrement() and AG_ScrollbarSetRealIncrement() define by how much the value is to be incremented/decremented as a result of the user clicking on the scrollbar buttons or using the keyboard to move the control. The former is only meaningful with integer bindings, the latter is only meaningful with floating-point bindings.

BINDINGS

The AG_Scrollbar widget provides the following bindings:

`float *{value,min,max,visible}`	Single precision position/range
`double *{value,min,max,visible}`	Double precision position/range
`long double *{value,min,max,visible}`	Quad precision position/range
`int *{value,min,max,visible}`	Integer position/range
`Uint *{value,min,max,visible}`	Unsigned position/range
`Uint8 *{value,min,max,visible}`	Unsigned 8-bit position/range
`Uint16 *{value,min,max,visible}`	Unsigned 16-bit position/range
`Uint32 *{value,min,max,visible}`	Unsigned 32-bit position/range
`Uint64 *{value,min,max,visible}`	Unsigned 64-bit position/range
`Sint8 *{value,min,max,visible}`	Signed 8-bit position/range
`Sint16 *{value,min,max,visible}`	Signed 16-bit position/range
`Sint32 *{value,min,max,visible}`	Signed 32-bit position/range
`Uint64 *{value,min,max,visible}`	Signed 64-bit position/range

The scrollbar is positioned to represent value inside of the range defined by min and max. In scrolling applications, visible is typically used to conveniently represent the size of the display area (its value is simply subtracted from the range).

Note that the min, max and visible bindings must be of the same type as value.

The Uint64, Sint64 and long double types are only available on platforms which support these types. The Uint64, Sint64 and long double types are only available on platforms which support these types.

EVENTS

The AG_Scrollbar widget reacts to the following events:

mouse-button-down	Seek to a position or initiate scrolling.
mouse-button-up	Terminate scrolling.
mouse-motion	Execute scrolling.

The AG_Scrollbar widget generates the following events:

scrollbar-changed (void)	The scrollbar's value has changed.
scrollbar-drag-begin (void)	User is starting to drag the scrollbar.
scrollbar-drag-end (void)	User is done dragging the scrollbar.

HISTORY

The AG_Scrollbar widget first appeared in Agar 1.0. The AG_SCROLLBAR_AUTOSIZE feature was introduced in Agar 1.4.0.