NAME

AG_Scrollbar —

agar scroll bar widget

SYNOPSIS

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

DESCRIPTION

The AG_Scrollbar widget provides a basic panning control. AG_Scrollbar is almost always used as part of a widget's implementation, where the user should be able to scroll over some partially visible graphics. The scrollbar's range and value parameters are specified by integer or floating-point bindings.

For example, in AG_Textbox(3), the max binding would be tied to the total line count, and value to the index of the first line to display. The visible binding would be tied to the number of lines that can be displayed on-screen (see BINDINGS).

NOTE: This widget is meant only as a panning control. For general edition of numerical values, the simpler AG_Slider(3) or AG_Numerical(3) widgets should be used.

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);

void
AG_ScrollbarSizeHint(AG_Scrollbar *scrollbar, int length);

void
AG_ScrollbarSetControlLength(AG_Scrollbar *scrollbar, int length);

void
AG_ScrollbarSetWidth(int width);

int
AG_ScrollbarWidth(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, ...);

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

AG_SCROLLBAR_NOAUTOHIDE: Always display the scrollbar. By default, the scrollbar is automatically hidden if the values of min, max and visible do not allow any room for scrolling.
AG_SCROLLBAR_EXCL: Advise that no external changes to the value, min, max and visible bindings are expected. By default, the binding values are periodically checked and the scrollbar is redrawn if a change is detected. Note that this setting only influences redraw -- external changes to the binding values are handled safely regardless.
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.

The AG_ScrollbarSizeHint() function specifies a default, preferred scrollbar length in pixels. This is rarely used; in practice, scrollbars almost always use AG_SCROLLBAR_HFILL or AG_SCROLLBAR_VFILL.

The AG_ScrollbarSetControlLength() function sets the size of the scrolling control in pixels. Note that this parameter is ignored if the visible binding is set to a non-zero value (in which case, the optimal size of the control is determined automatically).

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

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).

BINDINGS

The AG_Scrollbar widget provides the following bindings:

float *{value,min,max,inc,visible}: Single precision number
double *{value,min,max,inc,visible}: Double precision number
long double *{value,min,max,inc,visible}: Quad precision number
int *{value,min,max,inc,visible}: Natural integer
Uint *{value,min,max,inc,visible}: Unsigned integer
[SU]int8 *{value,min,max,inc,visible}: Fixed 8-bit integer
[SU]int16 *{value,min,max,inc,visible}: Fixed 16-bit integer
[SU]int32 *{value,min,max,inc,visible}: Fixed 32-bit integer
[SU]int64 *{value,min,max,inc,visible}: Fixed 64-bit integer

The scrollbar is positioned to represent value inside of a given range defined by min and max. The range defaults to 0.0 to 1.0 (for floating-point values), or 0 to the maximum representible value (for integer values).

Thea optional inc binding specifies the increment effected by the buttons, or keyboard. If not specified, it defaults to 0.1 (for floating-point values), or 1 (for integer values).

The optional visible binding may be set to indicate the portion of the total range which is currently visible on-screen. If this is a non-zero value, then the size of the scrolling control button will be set automatically.

Note that the min, max, inc and visible bindings must share the same type as value. The 64-bit types are only available if AG_HAVE_64BIT is set, and long double is only available if AG_HAVE_LONG_DOUBLE is set.

EVENTS

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.

STRUCTURE DATA

For the AG_Scrollbar object:

int width: Scrollbar width in pixels.
int hArrow: Size of "arrow" icons in pixels.

HISTORY

The AG_Scrollbar widget first appeared in Agar 1.0. The AUTOSIZE option was introduced in Agar 1.4.0. The inc binding was introduced in Agar 1.5.0.