.\" Copyright (c) 2002-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" 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 December 21, 2022
.Dt AG_SCROLLBAR 3
.Os Agar 1.7
.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
.\" IMAGE(/widgets/AG_Scrollbar.png, "An AG_Scrollbar")
The
.Nm
widget provides a basic panning control.
.Nm
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.
.Pp
For example, in
.Xr AG_Textbox 3 ,
the
.Va max
binding would be tied to the total line count, and
.Va value
to the index of the first line to display.
The
.Va visible
binding would be tied to the number of lines that can be displayed on-screen
(see
.Sx BINDINGS ) .
.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_ScrollbarNewHoriz "AG_Widget *parent" "Uint flags"
.Pp
.Ft "AG_Scrollbar *"
.Fn AG_ScrollbarNewVert "AG_Widget *parent" "Uint flags"
.Pp
.Ft int
.Fn AG_ScrollbarIsUseful "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
.nr nS 0
The
.Fn AG_ScrollbarNew
function allocates, initializes, and attaches a new
.Nm
widget.
The
.Fa type
argument should be either
.Dv AG_SCROLLBAR_HORIZ
to create a horizontal scrollbar, or
.Dv AG_SCROLLBAR_VERT
to create a vertical scrollbar.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_SCROLLBAR_EXPAND "
.It 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.
.It AG_SCROLLBAR_EXCL
Advise that no external changes to the
.Va value ,
.Va min ,
.Va max
and
.Va 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.
.It AG_SCROLLBAR_HFILL
Expand horizontally in parent container.
.It AG_SCROLLBAR_VFILL
Expand vertically in parent container.
.It AG_SCROLLBAR_EXPAND
Shorthand for
.Dv AG_SCROLLBAR_HFILL | AG_SCROLLBAR_VFILL .
.It AG_SCROLLBAR_TEXT
Display the minimum, current and maximum values in text.
This is primarily useful for debugging.
.El
.Pp
.Fn 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
.Fn size_allocate
in order to determine whether scrollbars need to be allocated or not.
.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).
.Sh BINDINGS
The
.Nm
widget provides the following bindings:
.Pp
.Bl -tag -compact -width "[SU]int64 *{value,min,max,inc,visible} "
.It Va float *{value,min,max,inc,visible}
Single precision number
.It Va double *{value,min,max,inc,visible}
Double precision number
.It Va int *{value,min,max,inc,visible}
Natural integer
.It Va Uint *{value,min,max,inc,visible}
Unsigned integer
.It Va [SU]int8 *{value,min,max,inc,visible}
Fixed 8-bit integer
.It Va [SU]int16 *{value,min,max,inc,visible}
Fixed 16-bit integer
.It Va [SU]int32 *{value,min,max,inc,visible}
Fixed 32-bit integer
.It Va [SU]int64 *{value,min,max,inc,visible}
Fixed 64-bit integer
.El
.Pp
The scrollbar is positioned to represent
.Va value
inside of a given range defined by
.Va min
and
.Va max .
The range defaults to 0.0 to 1.0 (for floating-point values),
or 0 to the maximum representible value (for integer values).
.Pp
Thea optional
.Va 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).
.Pp
The optional
.Va 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.
.Pp
Note that the
.Va min ,
.Va max ,
.Va inc
and
.Va visible
bindings must share the same type as
.Va value .
The 64-bit types are only available if
.Dv AG_HAVE_64BIT
is set.
.Sh EVENTS
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 STRUCTURE DATA
For the
.Ft AG_Scrollbar
object:
.Pp
.Bl -tag -compact -width "int visible "
.It Ft int width
Scrollbar width in pixels.
.It Ft int hArrow
Size of "arrow" icons in pixels.
.El
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Numerical 3 ,
.Xr AG_Scrollview 3 ,
.Xr AG_Slider 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
The
.Va inc
binding was introduced in Agar 1.5.0.
Agar 1.6.0 added the
.Dv AG_SCROLLBAR_SMOOTH
option and renamed
.Fn AG_ScrollbarVisible
to
.Fn AG_ScrollbarIsUseful .