<-- Back to AG_Intro.3


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


The AG_Button widget implements a simple push-button containing a text label or an image. AG_Button can trigger events and/or control a boolean value (which can be an integer or one or more bits in an integer).


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


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_ButtonInvertState (AG_Button *button, int flag)

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_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 boolean state of the button (the state binding) to a specified integer, where 1 is true and 0 is false.

The AG_ButtonNew{Flag,Flag8,Flag16,Flag32} ,() functions tie the boolean state of the button to the bits described by bitmask, within the specified integer.

To invert the boolean interpretation of the tied value, the button can be initialized with AG_BUTTON_INVSTATE, or a parameter of 1 can be passed to AG_ButtonInvertState().

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 label (use AG_LabelSetPadding(3) on the lbl member of the AG_Button to configure 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 focus.

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

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

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

The AG_ButtonSetRepeatMode() flag enables or disables repeat mode. Repeat mode causes multiple button-pushed events to be posted periodically for as long as the button is triggered. Repeat mode is used notably 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.


The following flags are provided:
AG_BUTTON_STICKYPrevent the button from springing back to its previous state following a click. Set on initialization or by AG_ButtonSetSticky().
AG_BUTTON_MOUSEOVERThe cursor is over the button area (read-only).
AG_BUTTON_REPEATRepeat mode is enabled (read-only, see AG_ButtonSetRepeatMode()).
AG_BUTTON_INVSTATEInvert the interpretation of the "state" binding. By default, a value of 1 causes the button to be pressed.
AG_BUTTON_EXCLDisable the test for redrawing the button upon external changes to the "state" binding.
AG_BUTTON_HFILLExpand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_BUTTON_VFILLExpand vertically in parent (equivalent to invoking AG_ExpandVert(3)).


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 argument indicates the new state of the button.


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


The following code fragment creates a button and sets a handler function for the button-pushed event:
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;

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


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


The AG_Button widget first appeared in Agar 1.0.