AG_UCOMBO(3)

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