AG_UCOMBO(3)

NAME
AG_UCombo - agar canned button + drop-down menu widget

SYNOPSIS

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

DESCRIPTION
The AG_UCombo widget displays an AG_Button(3), which causes a popup AG_Tlist(3) to be displayed when pressed. The list disappears when an option is selected.

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

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

AG_UCombo * AG_UComboNewPolled(AG_Widget *parent, Uint flags, AG_EventFn fn, const char *fmt, ...)

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 (equivalent to invoking AG_ExpandHoriz(3)).

AG_UCOMBO_VFILL
    Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).

AG_UCOMBO_EXPAND
    Shorthand for AG_UCOMBO_HFILL|AG_UCOMBO_VFILL.

The AG_UComboNewPolled() constructor configures a polled AG_Tlist(3) and assigns the polling function.

The AG_UComboSizeHint() function 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.

STRUCTURE DATA
For the AG_UCombo object:

AG_Tlist *list
    Pointer to the AG_Tlist(3) displayed by AG_UCombo when expanded (read-only).
AG_Button *button
    Pointer to the underlying AG_Button(3) widget (read-only).

EXAMPLES
The following code fragment reacts to a AG_UCombo selection event by displaying a text dialog:

    void
    Selected(AG_Event *event)
    {
    	AG_TlistItem *item = AG_PTR(1);
    	AG_TextMsg(AG_MSG_INFO, "Selected item: %s", item->text);
    }
    ...
    AG_UCombo *com;
    com = AG_UComboNew(NULL, 0);
    AG_TlistAdd(com->list, NULL, "Foo");
    AG_TlistAdd(com->list, NULL, "Bar");
    AG_SetEvent(com, "ucombo-selected", Selected, 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.