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

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".