<-- Back to AG_Intro.3

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