Agar


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 * Fn AG_ButtonNew{Int,Uint8,Uint16,Uint32} "AG_Widget *parent" "Uint flags" "const char *label" "<Type> *p"
AG_Button * Fn 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, 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.

The Fn 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 Fn AG_ButtonNew{Flag,Flag8,Flag16,Flag32} ,functions tie the state of the button with the state of the bits described by bitmask in the specified 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 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_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_HFILLExpand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_BUTTON_VFILLExpand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_BUTTON_EXPANDShorthand for AG_BUTTON_HFILL|AG_BUTTON_VFILL.

EVENTS

The AG_Button widget reacts to the following events:
mouse-button-upRelease the button if the cursor is inside the widget area.
mouse-button-downPress the button.
key-upRelease the button, unless sticky mode is in effect.
key-downPress the button.
mouse-motionAbort 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);

SEE ALSO

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

HISTORY

The AG_Button widget first appeared in Agar 1.0.