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

FreeBSD Manual Pages

  
 
  

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

NAME
       AG_Checkbox -- agar checkbox widget

SYNOPSIS
       #include	<agar/core.h>
       #include	<agar/gui.h>

DESCRIPTION
       The  AG_Checkbox	 widget	controls a boolean variable (i.e., an int or a
       set of bits in an integer).  If a text label is specified, it  is  dis-
       played next to the control.

INHERITANCE HIERARCHY
       AG_Object(3) -> AG_Widget(3) -> AG_Checkbox.

INITIALIZATION
       AG_Checkbox  * AG_CheckboxNew(AG_Widget *parent,	Uint flags, const char
       *format,	...)

       AG_Checkbox * AG_CheckboxNewS(AG_Widget *parent,	Uint flags, const char
       *label)

       AG_Checkbox * AG_CheckboxNewFn(AG_Widget	 *parent,  Uint	 flags,	 const
       char *label, AG_EventFn fn, const char *fmt, ...)

       AG_Checkbox  *  AG_CheckboxNewInt(AG_Widget  *parent, Uint flags, const
       char *label, int	*pBool)

       AG_Checkbox * AG_CheckboxNewUint(AG_Widget *parent, Uint	 flags,	 const
       char *label, Uint *pBool)

       AG_Checkbox  *  AG_CheckboxNewFlag(AG_Widget *parent, Uint flags, const
       char *label, Uint *pFlags, Uint bitmask)

       void  AG_CheckboxSetFromFlags(AG_Widget	*parent,  Uint	 flags,	  Uint
       *pFlags,	const AG_FlagDescr *flagsDescr)

       void  AG_CheckboxSetFromFlagsFn(AG_Widget  *parent,  Uint  flags,  Uint
       *pFlags,	const AG_FlagDescr  *flagsDescr,  AG_EventFn  fn,  const  char
       *fmt, ...)

       int AG_CheckboxGetState(AG_Checkbox *checkbox)

       void AG_CheckboxSetState(AG_Checkbox *checkbox, int enable)

       void AG_CheckboxToggle(AG_Checkbox *checkbox)

       The  AG_CheckboxNew()  function	allocates, initializes,	and attaches a
       AG_Checkbox widget.  AG_CheckboxNew() accepts an	 optional  text	 label
       argument.   The	AG_CheckboxNewFn()  variant also assigns the specified
       callback	function to the	`checkbox-changed' event.

       Acceptable values for the flags argument	include:

       AG_CHECKBOX_INVERT   Invert the logical interpretation of "state".

       AG_CHECKBOX_SET	    Set	default	"state"	to 1 (default =	0).

       AG_CHECKBOX_EXCL	    Advise that	this checkbox is the only  widget  ac-
			    cessing  "state"  (so  periodic  updates  are  not
			    needed).

       AG_CHECKBOX_HFILL    Expand horizontally	in parent container.

       AG_CHECKBOX_VFILL    Expand vertically in parent	container.

       AG_CHECKBOX_EXPAND   Shorthand	   for	     AG_CHECKBOX_HFILL	     |
			    AG_CHECKBOX_VFILL.

       The AG_CheckboxNewInt() constructor binds "state" to a natural integer.
       AG_CheckboxNewFlag()  binds  "state" to one or more bits	in the natural
       integer at pFlags, according to bitmask a.

       AG_CheckboxSetFromFlags() creates a set of checkboxes for the given set
       of flags, described by an array of AG_FlagDescr structures:

       typedef struct ag_flag_descr {
	       Uint bitmask;		       /* Bitmask */
	       const char *descr;	       /* Bit(s) description */
	       int writeable;		       /* User-editable	*/
       } AG_FlagDescr;

       The AG_CheckboxSetFromFlagsFn() variant	sets  the  event  handler  for
       `checkbox-changed' to the given function	fn and optional	arguments fmt.

       AG_CheckboxGetState()  returns  the  current  state  of	the  checkbox.
       AG_CheckboxSetState() sets the of the checkbox,	where  0=inactive  and
       0=active.  AG_CheckboxToggle() inverts the state	atomically.

BINDINGS
       The AG_Checkbox widget provides the following bindings:

       BOOL *state	Value (1/0) of natural integer
       INT *state	Value (1/0) of natural integer
       UINT8 *state	Value (1/0) of 8-bit integer
       UINT16 *state	Value (1/0) of 16-bit integer
       UINT32 *state	Value (1/0) of 32-bit integer
       FLAGS *state	Bits in	an int
       FLAGS8 *state	Bits in	8-bit word
       FLAGS16 *state	Bits in	16-bit word
       FLAGS32 *state	Bits in	32-bit word

EVENTS
       The AG_Checkbox widget generates	the following events:

       checkbox-changed(int state)
	   Checkbox  state changed (1=enabled, 0=disabled).  The `state' bind-
	   ing remains locked during the event handler's execution.

STRUCTURE DATA
       For the AG_Checkbox object:

       int invert      Invert the logical interpretation of the	`state'	 bind-
		       ing.

       AG_Label	*lbl   Pointer to the AG_Label(3) displaying the caption text.

EXAMPLES
       The  following  code fragment ties an AG_Checkbox to a boolean variable
       represented by an int:

	     int someOption = 0;

	     AG_Window *win = AG_WindowNew(0);
	     AG_CheckboxNewInt(win, 0, "Some option", &someOption);
	     AG_WindowShow(win);

       The following code fragment uses	an AG_Checkbox to trigger  a  callback
       function:

	     static void
	     MyCallback(AG_Event *event)
	     {
		     AG_TextInfo(NULL, "Callback invoked");
	     }

	     AG_Window *win = AG_WindowNew(0);
	     AG_CheckboxNewFn(win, 0, "Execute callback", MyCallback, NULL);
	     AG_WindowShow(win);

       The  following  code fragment creates an	array of checkboxes, each tied
       to a specific bit in a word:

	     #define FLAG_FOO	     0x01
	     #define FLAG_BAR	     0x02
	     #define FLAG_BAZ	     0x04

	     int myWord	= 0;

	     AG_FlagDescr myFlagDescr[]	= {
		     { FLAG_FOO,     "foo flag",	     1 },
		     { FLAG_BAR,     "bar flag",	     1 },
		     { FLAG_BAZ,     "baz flag (readonly)",  0 },
		     { 0,	     NULL,		     0 }
	     };

	     AG_Window *win = AG_WindowNew(0);
	     AG_CheckboxSetFromFlags(win, 0, &myWord, myFlagDescr);
	     AG_WindowShow(win);

SEE ALSO
       AG_Button(3),  AG_Event(3),  AG_Intro(3),  AG_Radio(3),	 AG_Widget(3),
       AG_Window(3)

HISTORY
       The    AG_Checkbox    widget    first	appeared    in	  Agar	  1.0.
       AG_CheckboxToggle(),  AG_CheckboxGetState()  and	 AG_CheckboxSetState()
       appeared	in Agar	1.6.0.

Agar 1.7		       December	21, 2022		AG_CHECKBOX(3)

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

home | help