NAME

AG_UCombo — agar button-triggered drop-down menu widget

SYNOPSIS

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

DESCRIPTION

The AG_UCombo widget displays an AG_Button(3) which triggers the expansion of drop-down menu (a window containing an AG_Tlist(3)) when pressed. The drop-down menu collapses if the user selects an item, or clicks outside of the AG_UCombo area.

INHERITANCE HIERARCHY

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

INITIALIZATION

AG_UCombo *
AG_UComboNew(AG_Widget *parent, Uint flags);

void
AG_UComboSizeHint(AG_UCombo *com, const char *text, int nitems);

void
AG_UComboSizeHintPixels(AG_UCombo *com, int w, int h);

The AG_UComboNew() function allocates, initializes, and attaches a new AG_UCombo widget. Acceptable flags include:

AG_UCOMBO_SCROLLTOSEL

Scroll to initial selection if it is not visible.

AG_UCOMBO_HFILL

Expand horizontally in parent container.

AG_UCOMBO_VFILL

Expand vertically in parent container.

AG_UCOMBO_EXPAND

Shorthand for AG_UCOMBO_HFILL | AG_UCOMBO_VFILL.

AG_UComboSizeHint() arranges for the AG_Tlist(3) widget displayed on popup to request a size large enough to display the given number of items. The AG_UComboSizeHintPixels() variant specifies the size of the list in pixels.

EVENTS

The AG_UCombo widget generates the following events:

ucombo-selected(AG_TlistItem *item)

An item was selected.

ucombo-expanded(void)

The drop-down menu is now visible.

ucombo-collapsed(void)

The drop-down menu is now hidden.

STRUCTURE DATA

For the AG_UCombo object:

AG_Tlist *list

The AG_Tlist(3) displayed by AG_UCombo when expanded, or NULL if collapsed (RO).

AG_Button *button

The AG_Button(3) which triggers expansion (RO).

EXAMPLES

The following code fragment generates a drop-down menu and reacts to a selection event by displaying a text dialog:

static void
ComboExpanded(AG_Event *event)
{
	AG_UCombo *com = AG_UCOMBO_SELF();

	AG_TlistAdd(com, NULL, "Foo");
	AG_TlistAdd(com, NULL, "Bar");
}

static void
ComboSelected(AG_Event *event)
{
	AG_TlistItem *item = AG_TLISTITEM_PTR(1);

	AG_TextMsg(AG_MSG_INFO, "Selected item: %s", item->text);
}

AG_UCombo *com;

com = AG_UComboNew(NULL, 0);
AG_SetEvent(com, "ucombo-expanded", ComboExpanded, NULL);
AG_SetEvent(com, "ucombo-selected", ComboSelected, NULL);

SEE ALSO

AG_Button(3), AG_Combo(3), AG_Intro(3), AG_Tlist(3), AG_Widget(3), AG_Window(3)

HISTORY

The AG_UCombo widget first appeared in Agar 1.0. "ucombo-expanded" and "ucombo-selected" appeared in Agar 1.7.0. The AG_Tlist(3) was formerly pre-generated and attached to the window on expansion, but as of Agar 1.7.0 the list member is now initialized to NULL and the list must be generated on demand from "ucombo-expanded".