NAME

AG_Radio — agar radio group widget

SYNOPSIS

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

DESCRIPTION

The AG_Radio widget implements a group of "radio" buttons.

INHERITANCE HIERARCHY

AG_Object(3) -> AG_Widget(3) -> AG_Radio.

INITIALIZATION

AG_Radio *
AG_RadioNew(AG_Widget *parent, Uint flags, const char *items[]);

AG_Radio *
AG_RadioNewFn(AG_Widget *parent, Uint flags, const char *items[], AG_EventFn fn, const char *fmt, ...);

AG_Radio *
AG_RadioNewInt(AG_Widget *parent, Uint flags, const char *items[], int *value);

AG_Radio *
AG_RadioNewUint(AG_Widget *parent, Uint flags, const char *items[], Uint *value);

void
AG_RadioSetDisposition(AG_Radio *radio, AG_RadioType type);

void
AG_RadioItemsFromArray(AG_Radio *radio, const char *items[]);

void
AG_RadioSizeHint(AG_Radio *radio, Uint nLines, const char *text);

int
AG_RadioAddItem(AG_Radio *radio, const char *format, ...);

int
AG_RadioAddItemS(AG_Radio *radio, const char *text);

int
AG_RadioAddItemHK(AG_Radio *radio, AG_KeySym hotkey, const char *format, ...);

int
AG_RadioAddItemHKS(AG_Radio *radio, AG_KeySym hotkey, const char *text);

void
AG_RadioClearItems(AG_Radio *radio);

The AG_RadioNew() function allocates, initializes, and attaches a new AG_Radio widget. If items is not NULL, it should point to a NULL-terminated array of strings. Acceptable flags include:

AG_RADIO_HOMOGENOUS

Divide space equally between radio items.

AG_RADIO_HFILL

Expand horizontally in parent container.

AG_RADIO_VFILL

Expand vertically in parent container.

AG_RADIO_EXPAND

Shorthand for AG_RADIO_HFILL | AG_RADIO_VFILL.

AG_RadioNewFn() creates a new radio group and also sets an event handler for the ‘radio-changed’ event.

AG_RadioNew{Int,Uint}() creates a new radio group bound to an integer.

AG_RadioSetDisposition() selects whether items are packed horizontally or vertically (the default):

typedef enum ag_radio_type {
	AG_RADIO_VERT,                  /* Vertical disposition */
	AG_RADIO_HORIZ                  /* Horizontal disposition */
} AG_RadioType;

AG_RadioItemsFromArray() generates (appends) a set of radio buttons from the given NULL-terminated array of C strings.

AG_RadioSizeHint() specifies an alternate initial size requisition expressed as a number of lines nLines (or -1 = auto) and the rendered pixel width of text (or NULL = auto). By default, AG_Radio will auto-size based on the set of radio items at the time of the size requisition.

AG_RadioAddItem() inserts a single radio button. The AG_RadioAddItemHK() variant also assigns a hotkey to the button.

AG_RadioClearItems() removes all radio buttons from the group.

BINDINGS

The AG_Radio widget provides the following bindings:

int *value

Index of selected item, or -1 if there is no selection.

EVENTS

The AG_Radio widget generates the following events:

radio-changed(int index)

Selection changed to item at index index. The ‘value’ binding remains locked throughout the event handler's execution.

STRUCTURE DATA

For the AG_Radio object:

int oversel

Index of last selection under the cursor (read-only).

EXAMPLES

The following code fragment connects an AG_Radio to an enum:

enum fruit {
	APPLE,
	ORANGE,
	BANANA
} fruit = APPLE;

const char *fruitNames[] = {
	"Apple",
	"Orange",
	"Banana",
	NULL
};

AG_RadioNewInt(NULL, 0, fruitNames, &fruit);

The following code fragment specifies a callback routine:

void
MyCallback(AG_Event *event)
{
	const int newSelection = AG_INT(1);

	printf("Selected item %d\n", newSelection);
}

...

AG_Radio *rad;

rad = AG_RadioNewFn(NULL, 0, fruitNames, MyCallback, NULL);
AG_BindInt(rad, "value", &fruit);

SEE ALSO

AG_Intro(3), AG_Widget(3), AG_Window(3)

HISTORY

The AG_Radio widget first appeared in Agar 1.0. AG_RadioSetDisposition() and AG_RadioSizeHint() appeared in Agar 1.6.0. The AG_RADIO_HOMOGENOUS option appeared in Agar 1.6.1.