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_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 * Fn AG_RadioNew{Int,Uint} "AG_Widget *parent" "Uint flags" "const char *items[]" "<Type> *value"
void AG_RadioItemsFromArray (AG_Radio *radio, const char *items[])

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_HFILL	Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_RADIO_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_RADIO_EXPAND	Shorthand for AG_RADIO_HFILL\|AG_RADIO_VFILL.

The AG_RadioNewFn() variant sets an event handler for the radio-changed event. The Fn AG_RadioNew{Int,Uint}variants tie the radio button with the specified int or Uint variable.

The AG_RadioItemsFromArray() function inserts a set of radio buttons from the given NULL-terminated array of strings. If there are already buttons in the group, they are preserved.

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

mouse-button-down	Select a radio item.
key-down	AG_KEY_DOWN moves selection downards. AG_KEY_UP moves selection upwards.

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 binds AG_Radio to an enum:

enum fruit {
	APPLE,
	ORANGE,
	BANANA
} fruit = APPLE;
const char *fruitNames[] = {
	"Apple",
	"Orange",
	"Banana",
	NULL
};
AG_Radio *r = AG_RadioNew(NULL, 0, fruitNames);
AG_BindInt(r, "value", &fruit);

To specify a callback routine:

void
MyCallback(AG_Event *event)
{
	int newSelection = AG_INT(1);
	printf("Selected item %d\\n", newSelection);
}
AG_Radio *r = AG_RadioNewFn(NULL, 0, fruitNames, MyCallback, NULL);
AG_BindInt(r, "value", &fruit);

HISTORY

The AG_Radio widget first appeared in Agar 1.0.