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_Checkbox widget displays a string of text next to a button used to trigger an int binding.

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_CheckboxNewFlag (AG_Widget *parent, Uint flags, const char *label, Uint *pFlags, Uint bitmask)

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

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

"AG_Checkbox *"() AG_CheckboxSetFromFlags32 (AG_Widget *parent, Uint flags, Uint32 *pFlags, const AG_FlagDescr *flagsDescr)

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_SET	Set the state to 1 on initialization.
AG_CHECKBOX_HFILL	Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_CHECKBOX_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_CHECKBOX_EXPAND	Shorthand for AG_CHECKBOX_HFILL\|AG_CHECKBOX_VFILL.

The AG_CheckboxNewInt() variant binds the state to a boolean integer.

AG_CheckboxNewFlag() binds the state to a specified set of bits bitmask in pFlags.

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;

The AG_CheckboxToggle() function inverts the current state of checkbox.

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

mouse-button-down	Trigger the state if button is 1, otherwise only give focus to the widget.
key-down	Trigger the state if key is AG_KEY_RETURN or AG_KEY_SPACE.

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:

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

HISTORY

The AG_Checkbox widget first appeared in Agar 1.0.