Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

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_ButtonNewInt (AG_Widget *parent, Uint flags, const char *label, int *p)

AG_Button * AG_ButtonNewUint8 (AG_Widget *parent, Uint flags, const char *label, Uint8 *p)

AG_Button * AG_ButtonNewUint16 (AG_Widget *parent, Uint flags, const char *label, Uint16 *p)

AG_Button * AG_ButtonNewUint32 (AG_Widget *parent, Uint flags, const char *label, Uint32 *p)

AG_Button * AG_ButtonNewFlag (AG_Widget *parent, Uint flags, const char *label, Uint *p, Uint bitmask)

AG_Button * AG_ButtonNewFlag8 (AG_Widget *parent, Uint flags, const char *label, Uint8 *p, Uint8 bitmask)

AG_Button * AG_ButtonNewFlag16 (AG_Widget *parent, Uint flags, const char *label, Uint16 *p, Uint16 bitmask)

AG_Button * AG_ButtonNewFlag32 (AG_Widget *parent, Uint flags, const char *label, Uint32 *p, Uint32 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, 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.

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.

AG_ButtonNewInt(), AG_ButtonNewUint8(), AG_ButtonNewUint16() and AG_ButtonNewUint32() associate the state of the button (the state binding) with the given integer, where a value of 0 is false and 1 is true.

AG_ButtonNewFlag(), AG_ButtonNewFlag8(), AG_ButtonNewFlag16() and AG_ButtonNewFlag32() associate the state of the button with the state of one or more bits (as described by bitmask) in the given integer.

The caption argument, if not NULL, defines the string to display by default as button label. See BUTTON FLAGS for the acceptable flags values.

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.

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. 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_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 reacts to the following events:

mouse-button-up	Release the button if the cursor is inside the widget area.
mouse-button-down	Press the button.
key-up	Release the button, unless sticky mode is in effect.
key-down	Press the button.
mouse-motion	Abort a button press if the cursor is moving outside the button area and sticky mode is not in effect.

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.
button-mouseoverlap (int overlap)	The mouse cursor has entered/exited the button area. This is typically is used to display tool tips.

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));
}
 
Li ...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.