.\" Copyright (c) 2002-2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 11, 2002
.Dt AG_SCROLLBAR 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Scrollbar
.Nd agar scroll bar widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
widget allows the user to control an integer or floating-point value within a
specified range.
It is almost always used to control a scrollable view, and it features a
special
.Va visible
binding to faciliate this application.
.Pp
For general-purpose edition of numerical values,
.Xr AG_Slider 3
or
.Xr AG_Numerical 3
are more suitable alternatives.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INTERFACE
.nr nS 1
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNew "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewInt "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "int *val" "int *min" "int *max" "int *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewUint "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Uint *value" "Uint *min" "Uint *max" "Uint *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewUint8 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Uint8 *value" "Uint8 *min" "Uint8 *max" "Uint8 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewSint8 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Sint8 *value" "Sint8 *min" "Sint8 *max" "Sint8 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewUint16 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Uint16 *value" "Uint16 *min" "Uint16 *max" "Uint16 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewSint16 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Sint16 *value" "Sint16 *min" "Sint16 *max" "Sint16 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewUint32 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Uint32 *value" "Uint32 *min" "Uint32 *max" "Uint32 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewSint32 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Sint32 *value" "Sint32 *min" "Sint32 *max" "Sint32 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewUint64 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Uint64 *value" "Uint64 *min" "Uint64 *max" "Uint64 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewSint64 "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "Sint64 *value" "Sint64 *min" "Sint64 *max" "Sint64 *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewFloat "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "float *value" "float *min" "float *max" "float *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewDouble "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "double *value" "double *min" "double *max" "double *visible"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewLongDouble "AG_Widget *parent" "enum ag_scrollbar_type type" "Uint flags" "long double *value" "long double *min" "long double *max" "long double *visible"
.Pp
.Ft void
.Fn AG_ScrollbarSetBarSize "AG_Scrollbar *scrollbar" "int size"
.Pp
.Ft int
.Fn AG_ScrollbarGetBarSize "AG_Scrollbar *scrollbar"
.Pp
.Ft int
.Fn AG_ScrollbarVisible "AG_Scrollbar *scrollbar"
.Pp
.Ft void
.Fn AG_ScrollbarSetIncFn "AG_Scrollbar *scrollbar" "AG_EventFn fn" "const char *fmt" "..."
.Pp
.Ft void
.Fn AG_ScrollbarSetDecFn "AG_Scrollbar *scrollbar" "AG_EventFn fn" "const char *fmt" "..."
.Pp
.Ft void
.Fn AG_ScrollbarSetIntIncrement "AG_Scrollbar *scrollbar" "int increment"
.Pp
.Ft void
.Fn AG_ScrollbarSetRealIncrement "AG_Scrollbar *scrollbar" "double increment"
.Pp
.nr nS 0
The
.Fn AG_ScrollbarNew
function allocates, initializes, and attaches a new
.Nm
widget.
.Fa type
defines the orientation of the scrollbar:
.Bd -literal
enum ag_scrollbar_type {
	AG_SCROLLBAR_HORIZ,
	AG_SCROLLBAR_VERT
};
.Ed
.Pp
There are currently no
.Fa flags
specific to this widget.
.Pp
The
.Fn AG_ScrollbarNew*
variants create a scrollbar and also bind
.Va value ,
.Va min ,
.Va max ,
and
.Va visible
to the specified non-NULL variables.
.Fn AG_ScrollbarNewUint16 ,
.Fn AG_ScrollbarNewSint16
and
.Fn AG_ScrollbarNewLongDouble
are only available on platforms which support these types.
.Pp
The
.Fn AG_ScrollbarSetBarSize
function sets the size of the scrollbar in pixels.
In scrolling applications, the scrollbar size is usually computed from the
ratio between the visible area and the total area that can be displayed.
.Fn AG_ScrollbarGetBarSize
returns the current size of the scrollbar in pixels.
.Pp
.Fn AG_ScrollbarSetButtonSize
requests a preferred size for the scrollbar buttons.
.Fn AG_ScrollbarGetButtonSize
returns the current button size, which may be less than previously requested.
.Pp
The
.Fn AG_ScrollbarVisible
function returns 1 if the current range is such that the scrollbar is useful
to display, otherwise it returns 0.
.Pp
The
.Fn AG_ScrollbarSetDecFn
and
.Fn 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
.Ft int
argument is passed to the callback (1 = pressed, 0 = released).
.Pp
.Fn AG_ScrollbarSetIntIncrement
and
.Fn 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.
.Sh BINDINGS
The
.Nm
widget provides the following bindings:
.Pp
.Bl -tag -compact -width "long double *{value,min,max,visible} "
.It Va float *{value,min,max,visible}
Single precision position/range
.It Va double *{value,min,max,visible}
Double precision position/range
.It Va long double *{value,min,max,visible}
Quad precision position/range
.It Va int *{value,min,max,visible}
Integer position/range
.It Va Uint *{value,min,max,visible}
Unsigned position/range
.It Va Uint8 *{value,min,max,visible}
Unsigned 8-bit position/range
.It Va Uint16 *{value,min,max,visible}
Unsigned 16-bit position/range
.It Va Uint32 *{value,min,max,visible}
Unsigned 32-bit position/range
.It Va Uint64 *{value,min,max,visible}
Unsigned 64-bit position/range
.It Va Sint8 *{value,min,max,visible}
Signed 8-bit position/range
.It Va Sint16 *{value,min,max,visible}
Signed 16-bit position/range
.It Va Sint32 *{value,min,max,visible}
Signed 32-bit position/range
.It Va Uint64 *{value,min,max,visible}
Signed 64-bit position/range
.El
.Pp
The scrollbar is positioned to represent
.Va value
inside of the range defined by
.Va min
and
.Va max .
In scrolling applications,
.Va visible
is typically used to conveniently represent the size of the display area
(its value is simply subtracted from the range).
.Pp
Note that the
.Va min ,
.Va max
and
.Va visible
bindings must be of the same type as
.Va value .
.Pp
The
.Ft Uint64 ,
.Ft Sint64
and
.Ft long double
types are only available on platforms which support these types.
The
.Ft Uint64 ,
.Ft Sint64
and
.Ft long double
types are only available on platforms which support these types.
.Sh EVENTS
The
.Nm
widget reacts to the following events:
.Pp
.Bl -tag -compact -width 25n
.It window-mousebuttondown
Seek to a position or initiate scrolling.
.It window-mousebuttonup
Terminate scrolling.
.It window-mousemotion
Execute scrolling.
.El
.Pp
The
.Nm
widget generates the following events:
.Pp
.Bl -tag -compact -width 2n
.It Fn scrollbar-changed "void"
The scrollbar's value has changed.
.It Fn scrollbar-drag-begin "void"
User is starting to drag the scrollbar.
.It Fn scrollbar-drag-end "void"
User is done dragging the scrollbar.
.El
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Scrollview 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.