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
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.
|AG_Object(3)-> AG_Widget(3)-> AG_Scrollbar.|
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:
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).
AG_Scrollbar widget provides the following bindings:
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.
AG_Scrollbar widget generates the following events:
|AG_Intro(3), AG_Scrollview(3), AG_Slider(3), AG_Widget(3), AG_Window(3)|
|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.|