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

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 *
AG_ScrollbarNewHoriz(AG_Widget *parent, Uint flags);

AG_Scrollbar *
AG_ScrollbarNewVert(AG_Widget *parent, Uint flags);

int
AG_ScrollbarIsUseful(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_SMOOTH: Use an animated scrolling motion when clicking outside of the control bar area (in between the increment/decrement buttons and the control bar). The default behavior is to jump to the target position.
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 container.
AG_SCROLLBAR_VFILL: Expand vertically in parent container.
AG_SCROLLBAR_EXPAND: Shorthand for AG_SCROLLBAR_HFILL | AG_SCROLLBAR_VFILL.
AG_SCROLLBAR_TEXT: Display the minimum, current and maximum values in text. This is primarily useful for debugging.

AG_ScrollbarIsUseful() evaluates whether the current value ("value") can be moved within the current range ("min", "max"). It returns 1=Yes or 0=No. Container widgets may wish to call it from size_allocate() in order to determine whether scrollbars need to be allocated or not.

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

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 inc binding was introduced in Agar 1.5.0. Agar 1.6.0 added the AG_SCROLLBAR_SMOOTH option and renamed AG_ScrollbarVisible() to AG_ScrollbarIsUseful().