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 scroll-
     bar'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  out-
			   side  of  the control bar area (in between the incre-
			   ment/decrement buttons and the control bar).  The de-
			   fault 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 re-
			   gardless.

     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 de-
     termine 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 ar-
     gument 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  de-
     fined 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 val-
     ues), or 1 (for integer values).

     The optional visible binding may be set to indicate the portion of the  to-
     tal  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  automati-
     cally.

     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+15.1.quarterly>

home | help