AG_CHECKBOX(3)

NAME
AG_Checkbox - agar checkbox widget

SYNOPSIS

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

DESCRIPTION
The AG_Checkbox widget controls a boolean variable (i.e., an int or a set of bits in an integer). If a text label is specified, it is displayed next to the control.

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

INITIALIZATION
AG_Checkbox * AG_CheckboxNew(AG_Widget *parent, Uint flags, const char *format, ...)

AG_Checkbox * AG_CheckboxNewS(AG_Widget *parent, Uint flags, const char *label)

AG_Checkbox * AG_CheckboxNewFn(AG_Widget *parent, Uint flags, const char *label, AG_EventFn fn, const char *fmt, ...)

AG_Checkbox * AG_CheckboxNewInt(AG_Widget *parent, Uint flags, const char *label, int *pBool)

AG_Checkbox * AG_CheckboxNewUint(AG_Widget *parent, Uint flags, const char *label, Uint *pBool)

AG_Checkbox * AG_CheckboxNewFlag(AG_Widget *parent, Uint flags, const char *label, Uint *pFlags, Uint bitmask)

AG_Checkbox *() AG_CheckboxSetFromFlags(AG_Widget *parent, Uint flags, Uint *pFlags, const AG_FlagDescr *flagsDescr)

int AG_CheckboxGetState(AG_Checkbox *checkbox)

void AG_CheckboxSetState(AG_Checkbox *checkbox, int enable)

void AG_CheckboxToggle(AG_Checkbox *checkbox)

The AG_CheckboxNew() function allocates, initializes, and attaches a AG_Checkbox widget. AG_CheckboxNew() accepts an optional text label argument. The AG_CheckboxNewFn() variant also assigns the specified callback function to the ‘checkbox-changed’ event.

Acceptable values for the flags argument include:

AG_CHECKBOX_INVERT
    Invert the logical interpretation of "state".

AG_CHECKBOX_SET
    Set default "state" to 1 (default = 0).

AG_CHECKBOX_EXCL
    Advise that this checkbox is the only widget accessing "state" (so periodic updates are not needed).

AG_CHECKBOX_HFILL
    Expand horizontally in parent container.

AG_CHECKBOX_VFILL
    Expand vertically in parent container.

AG_CHECKBOX_EXPAND
    Shorthand for AG_CHECKBOX_HFILL | AG_CHECKBOX_VFILL.

The AG_CheckboxNewInt() constructor binds "state" to a natural integer. AG_CheckboxNewFlag() binds "state" to one or more bits in the natural integer at pFlags, according to bitmask a.

Note: While convenience constructors are only provided for natural integers, AG_Checkbox can also bind to fixed-size integers (see BINDINGS).

The utility function AG_CheckboxSetFromFlags() creates a set of checkboxes for the given set of flags, described by an array of AG_FlagDescr structures:

    typedef struct ag_flag_descr {
    	Uint bitmask;			/* Bitmask */
    	const char *descr;		/* Bit(s) description */
    	int writeable;			/* User-editable */
    } AG_FlagDescr;

AG_CheckboxGetState() returns the current state of the checkbox. AG_CheckboxSetState() sets the of the checkbox, where 0=inactive and 0=active. AG_CheckboxToggle() inverts the state atomically.

BINDINGS
The AG_Checkbox widget provides the following bindings:

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

EVENTS
The AG_Checkbox widget generates the following events:

checkbox-changed(int state)
    Checkbox state changed (1=enabled, 0=disabled). The ‘state’ binding remains locked during the event handler's execution.

STRUCTURE DATA
For the AG_Checkbox object:

int invert
    Invert the logical interpretation of the ‘state’ binding.

AG_Label *lbl
    Pointer to the AG_Label(3) displaying the caption text.

EXAMPLES
The following code fragment ties an AG_Checkbox to a boolean variable represented by an int:

    int someOption = 0;
    AG_Window *win = AG_WindowNew(0);
    AG_CheckboxNewInt(win, 0, "Some option", &someOption);
    AG_WindowShow(win);

The following code fragment uses an AG_Checkbox to trigger a callback function:

    static void
    MyCallback(AG_Event *event)
    {
    	AG_TextInfo(NULL, "Callback invoked");
    }
    AG_Window *win = AG_WindowNew(0);
    AG_CheckboxNewFn(win, 0, "Execute callback", MyCallback, NULL);
    AG_WindowShow(win);

The following code fragment creates an array of checkboxes, each tied to a specific bit in a word:

    #define FLAG_FOO	0x01
    #define FLAG_BAR	0x02
    #define FLAG_BAZ	0x04
    int myWord = 0;
    AG_FlagDescr myFlagDescr[] = {
    	{ FLAG_FOO,	"foo flag",		1 },
    	{ FLAG_BAR,	"bar flag",		1 },
    	{ FLAG_BAZ,	"baz flag (readonly)",	0 },
    	{ 0,		NULL,			0 }
    };
    AG_Window *win = AG_WindowNew(0);
    AG_CheckboxSetFromFlags(win, 0, &myWord, myFlagDescr);
    AG_WindowShow(win);

SEE ALSO
AG_Button(3), AG_Event(3), AG_Intro(3), AG_Radio(3), AG_Widget(3), AG_Window(3)

HISTORY
The AG_Checkbox widget first appeared in Agar 1.0. AG_CheckboxToggle(), AG_CheckboxGetState() and AG_CheckboxSetState() appeared in Agar 1.6.0.