AG_COMBO(3)

NAME
AG_Combo - agar canned text input + drop-down menu widget

SYNOPSIS

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

DESCRIPTION
The AG_Combo widget packs a AG_Textbox(3) widget left to a AG_Button(3), which causes a AG_Tlist(3) to popup when pressed. The tlist disappears when an option is selected.

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

INITIALIZATION
AG_Combo * AG_ComboNew(AG_Widget *parent, Uint flags, const char *format, ...)

AG_Combo * AG_ComboNewS(AG_Widget *parent, Uint flags, const char *label)

void AG_ComboSizeHint(AG_Combo *combo, const char *text, int nitems)

void AG_ComboSizeHintPixels(AG_Combo *combo, int w, int nitems)

The AG_ComboNew() function allocates, initializes, and attaches a new AG_Combo widget. The string argument specifies an optional text label to be displayed at the left of the textbox. Acceptable flags include:

AG_COMBO_POLL
    List contents are dynamic (pass the AG_TLIST_POLL flag to the tlist).

AG_COMBO_TREE
    List is a tree display (pass the AG_TLIST_TREE flag to the tlist).

AG_COMBO_ANY_TEXT
    Allow user to enter text that does not match any item in the list.

AG_COMBO_SCROLLTOSEL
    Scroll to initial selection if it is not visible.

AG_COMBO_HFILL
    Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).

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

AG_COMBO_EXPAND
    Shorthand for AG_COMBO_HFILL|AG_COMBO_VFILL.

The AG_ComboSizeHint() 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_ComboSizeHintPixels() variant specifies the width in number of pixels.

ITEM SELECTION
void AG_ComboSelect(AG_Combo *combo, AG_TlistItem *item)

AG_TlistItem * AG_ComboSelectPointer(AG_Combo *combo, void *ptr)

AG_TlistItem * AG_ComboSelectText(AG_Combo *combo, const char *text)

The AG_ComboSelect() function sets the selection flag on the given item.

The AG_ComboSelectPointer() function selects the first item with a user pointer value matching ptr. Similarly, AG_ComboSelectText() selects the first item with a text string equal to text.

If the AG_COMBO_POLL option is set, both AG_ComboSelectPointer() and AG_ComboSelectText() will raise a ‘tlist-poll’ event prior to making the selection.

EVENTS
The AG_Combo widget generates the following events:

combo-selected(AG_TlistItem *item)
    An item was selected.
combo-text-entry(const char *text)
    The AG_COMBO_ANY_TEXT option is set and the user has entered a string text which does not match any item in the list.
combo-text-unknown(const char *text)
    The AG_COMBO_ANY_TEXT flag is not set and the user has entered a string text which does not match any item in the list.

STRUCTURE DATA
For the AG_Combo object:

AG_Tlist *list
    Pointer to the AG_Tlist(3) displayed by AG_Combo when expanded (read-only).
AG_Textbox *tbox
    Pointer to the AG_Textbox(3) contained in the AG_Combo (read-only).
AG_Button *button
    Pointer to the AG_Button(3) next to the textbox (read-only).

EXAMPLES
The following code fragment reacts to a AG_Combo 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_Combo *com;
    com = AG_ComboNew(NULL, 0, "Item: ");
    AG_TlistAdd(com->list, NULL, "Foo");
    AG_TlistAdd(com->list, NULL, "Bar");
    AG_SetEvent(com, "combo-selected", Selected, NULL);

SEE ALSO
AG_Button(3), AG_Intro(3), AG_Textbox(3), AG_Tlist(3), AG_Widget(3), AG_Window(3)

HISTORY
The AG_Combo widget first appeared in Agar 1.0.