AG_RADIO(3)

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

SEE ALSO
AG_Intro(3), AG_Widget(3), AG_Window(3)

HISTORY
The AG_Radio widget first appeared in Agar 1.0.