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

FreeBSD Manual Pages

  
 
  

home | help
AG_BUTTON(3)	       FreeBSD Library Functions Manual		  AG_BUTTON(3)

NAME
     AG_Button -- agar button widget

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

DESCRIPTION
     The AG_Button widget implements a simple push-button displaying an	image
     or	a text label.  AG_Button can be	used to	trigger	events,	or control a
     boolean value.

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

INTERFACE
     AG_Button * AG_ButtonNew(AG_Widget	*parent, Uint flags, const char
     *format, ...)

     AG_Button * AG_ButtonNewS(AG_Widget *parent, Uint flags, const char
     *label)

     AG_Button * AG_ButtonNewFn(AG_Widget *parent, Uint	flags, const char
     *label, void (*fn)(AG_Event *), const char	*fnArgs, ...)

     AG_Button * AG_ButtonNew{Int,Uint8,Uint16,Uint32}(AG_Widget *parent, Uint
     flags, const char *label, _Type_ *p)

     AG_Button * AG_ButtonNew{Flag,Flag8,Flag16,Flag32}(AG_Widget *parent,
     Uint flags, const char *label, Uint *p, _Type_ bitmask)

     void AG_ButtonSetPadding(AG_Button	*button, int lPad, int rPad, int tPad,
     int bPad)

     void AG_ButtonSetFocusable(AG_Button *button, int flag)

     void AG_ButtonSetSticky(AG_Button *button,	int flag)

     void AG_ButtonInvertState(AG_Button *button, int flag)

     void AG_ButtonJustify(AG_Button *button, enum ag_text_justify justify)

     void AG_ButtonValign(AG_Button *button, enum ag_text_valign valign)

     void AG_ButtonSetRepeatMode(AG_Button *button, int	repeat_flag)

     void AG_ButtonSurface(AG_Button *button, const AG_Surface *su)

     void AG_ButtonSurfaceNODUP(AG_Button *button, AG_Surface *su)

     void AG_ButtonText(AG_Button *button, const char *format, ...)

     void AG_ButtonTextS(AG_Button *button, const char *label)

     The AG_ButtonNew()	function allocates, initializes, and attaches a
     AG_Button widget.	If the label argument is given,	it sets	a default text
     caption.  For the list of acceptable flags, see BUTTON FLAGS section.

     The AG_ButtonNewFn() variant creates a button and implicitely sets	a
     callback (event handler) function to be executed whenever the button is
     pressed.  See AG_Event(3) for details on Agar event handlers.  Since
     function-triggering buttons rarely	make use of the	"state"	binding,
     AG_ButtonNewFn() implies AG_BUTTON_EXCL (unless AG_BUTTON_NOEXCL is
     passed).

     The AG_ButtonNew{Int,Uint8,Uint16,Uint32}() functions tie the state of
     the button	(the `state' binding) with the given integer variable, where 1
     = True and	0 = False.

     The AG_ButtonNew{Flag,Flag8,Flag16,Flag32}(), functions tie the state of
     the button	with the state of the bits described by	bitmask	in the speci-
     fied integer variable.  AG_ButtonNewFlag()	binds to an int,
     AG_ButtonNewFlag8() binds to an Uint8, etc.

     The AG_ButtonSetPadding() function	sets the padding around	the label in
     pixels.  If a parameter is	-1, its	current	value is preserved.  Note that
     when using	a text label, this setting is independent from that of the la-
     bel (use AG_LabelSetPadding(3) on the lbl member of the AG_Button to con-
     figure the	text label padding as well).

     The AG_ButtonSetFocusable() function with an argument of 0	prevents the
     button from gaining focus.	 The default is	to allow buttons to gain fo-
     cus.

     The AG_ButtonSetSticky() function enables or disable sticky mode.	Under
     sticky mode, the button will not spring back to its previous state	fol-
     lowing a click event.  This mode is mostly	useful when the	button's state
     is	bound to a boolean variable.

     The AG_ButtonInvertState()	function defines whether to invert the meaning
     of	the boolean variable bound to the button.

     AG_ButtonJustify()	sets the justification for the button text label (or
     icon):

     enum ag_text_justify {
	     AG_TEXT_LEFT,
	     AG_TEXT_CENTER,
	     AG_TEXT_RIGHT
     };

     AG_ButtonValign() sets the	vertical alignment for the button text label
     (or icon):

     enum ag_text_valign {
	     AG_TEXT_TOP,
	     AG_TEXT_MIDDLE,
	     AG_TEXT_BOTTOM
     };

     The AG_ButtonSetRepeatMode() flag enables or disables repeat mode.	 Re-
     peat mode causes multiple `button-pushed' events to be posted periodi-
     cally for as long as the button is	triggered.  Repeat mode	is used	no-
     tably by AG_Numerical(3).

     AG_ButtonSurface()	sets the button	label to a copy	of the given surface.
     The AG_ButtonSurfaceNODUP() variant uses the given	surface	as source
     without copying.  If a text label currently exists, it is removed.

     AG_ButtonText() sets the label of the button from the specified text
     string.  If a surface is currently	set, it	is removed.

BUTTON FLAGS
     The following flags are provided:

     AG_BUTTON_STICKY	   Prevent the button from springing back to its pre-
			   vious state following a click.  Set on initializa-
			   tion	or by AG_ButtonSetSticky().

     AG_BUTTON_MOUSEOVER   The cursor is over the button area (read-only).

     AG_BUTTON_REPEAT	   Repeat mode is enabled (read-only, see
			   AG_ButtonSetRepeatMode()).

     AG_BUTTON_INVSTATE	   Invert the interpretation of	the "state" binding.
			   By default, a value of 1 causes the button to be
			   pressed.

     AG_BUTTON_EXCL	   Disable the test for	redrawing the button upon ex-
			   ternal changes to the "state" binding.

     AG_BUTTON_HFILL	   Expand horizontally in parent (equivalent to	invok-
			   ing AG_ExpandHoriz(3)).

     AG_BUTTON_VFILL	   Expand vertically in	parent (equivalent to invoking
			   AG_ExpandVert(3)).

     AG_BUTTON_EXPAND	   Shorthand for AG_BUTTON_HFILL|AG_BUTTON_VFILL.

EVENTS
     The AG_Button widget generates the	following events:

     button-pushed(int new_state)
	 The button was	pressed.  If using AG_BUTTON_STICKY, the new_state ar-
	 gument	indicates the new state	of the button.

BINDINGS
     The AG_Button widget provides the following bindings.  In all cases, a
     value of 1	is considered boolean TRUE, and	a value	of 0 is	considered
     boolean FALSE.

     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

EXAMPLES
     The following code	fragment creates a button and sets a handler function
     for the `button-pushed' event:

	   void
	   MyHandlerFn(AG_Event	*event)
	   {
		   AG_TextMsg(AG_MSG_INFO, "Hello, %s!", AG_STRING(1));
	   }

	   ...

	   AG_ButtonNewFn(parent, 0, "Hello", MyHandlerFn, "%s", "world");

     The following code	fragment uses buttons to control specific bits in a
     32-bit word:

	   Uint32 MyFlags = 0;

	   AG_ButtonNewFlag32(parent, 0, "Bit 1", &MyFlags, 0x01);
	   AG_ButtonNewFlag32(parent, 0, "Bit 2", &MyFlags, 0x02);

     The following code	fragment uses a	button to control an int protected by
     a mutex device:

	   int MyInt = 0;
	   AG_Mutex MyMutex;
	   AG_Button *btn;

	   AG_MutexInit(&MyMutex);
	   btn = AG_ButtonNew(parent, 0, "Mutex-protected flag");
	   AG_BindIntMp(btn, "state", &MyInt, &MyMutex);

SEE ALSO
     AG_Event(3), AG_Intro(3), AG_Surface(3), AG_Toolbar(3), AG_Widget(3),
     AG_Window(3)

HISTORY
     The AG_Button widget first	appeared in Agar 1.0.

FreeBSD	13.0			August 20, 2002			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INTERFACE | BUTTON FLAGS | EVENTS | BINDINGS | EXAMPLES | SEE ALSO | HISTORY

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

home | help