Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_SCROLLBAR(3)		    Library Functions Manual	       AG_SCROLLBAR(3)

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 to-
       tal 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 in-
       clude:

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

       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	influ-
			     ences  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 config-
       ure  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 = re-
       leased).

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	float-
       ing-point values), or 0 to the maximum representible value (for integer
       values).

       Thea optional inc binding specifies the increment effected by the  but-
       tons, 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.

SEE ALSO
       AG_Intro(3),	AG_Numerical(3),    AG_Scrollview(3),	 AG_Slider(3),
       AG_Widget(3), AG_Window(3)

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

Agar 1.7		       December	21, 2022	       AG_SCROLLBAR(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Scrollbar&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help