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

FreeBSD Manual Pages

  
 
  

home | help
AG_SCROLLBAR(3)	       FreeBSD 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	float-
     ing-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 dis-
     played on-screen (see BINDINGS).

     NOTE: This	widget is meant	only as	a panning control.  For	general	edi-
     tion of numerical values, the simpler AG_Slider(3)	or AG_Numerical(3)
     widgets should be used.

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)

     void AG_ScrollbarSizeHint(AG_Scrollbar *scrollbar,	int length)

     void AG_ScrollbarSetControlLength(AG_Scrollbar *scrollbar,	int length)

     void AG_ScrollbarSetWidth(int width)

     int AG_ScrollbarWidth(void)

     int AG_ScrollbarVisible(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_NOAUTOHIDE   Always display the scrollbar.  By default, the
			       scrollbar is automatically hidden if the	values
			       of min, max and visible do not allow any	room
			       for scrolling.

     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 regard-
			       less.

     AG_SCROLLBAR_HFILL	       Expand horizontally in parent (equivalent to
			       invoking	AG_ExpandHoriz(3)).  This flag is only
			       sensible	with horizontal	scrollbars, and	ren-
			       ders the	use of AG_ScrollbarSizeHint() unneces-
			       sary.

     AG_SCROLLBAR_VFILL	       Expand vertically in parent (equivalent to in-
			       voking AG_ExpandVert(3)).  This flag is only
			       sensible	with vertical scrollbars, and renders
			       the use of AG_ScrollbarSizeHint() unnecessary.

     AG_SCROLLBAR_EXPAND       Shorthand for
			       AG_SCROLLBAR_HFILL|AG_SCROLLBAR_VFILL.

     AG_SCROLLBAR_TEXT	       Display the minimum, current and	maximum	values
			       in text.	 This option is	primarily useful for
			       debugging.

     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 scroll-
     bar 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 decre-
     ment (up/left) button and the increment (down/right) buttons.  A single
     int argument 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
     long double *{value,min,max,inc,visible}	Quad 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 floating-
     point values), or 0 to the	maximum	representible value (for integer val-
     ues).

     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 automat-
     ically.

     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.

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_Scrollview(3), AG_Slider(3), AG_Widget(3),	AG_Window(3)

HISTORY
     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.

FreeBSD	13.0		      September	11, 2002		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INTERFACE | BINDINGS | EVENTS | STRUCTURE DATA | SEE ALSO | HISTORY

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

home | help