<-- Back to AG_Intro.3

SYNOPSIS

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

DESCRIPTION

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

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

BUTTON FLAGS

The following flags are provided:

AG_BUTTON_STICKY	Prevent the button from springing back to its previous state following a click. Set on initialization 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 external changes to the "state" binding.
AG_BUTTON_HFILL	Expand horizontally in parent (equivalent to invoking 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 argument 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);

HISTORY

The AG_Button widget first appeared in Agar 1.0.