Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_COMBO(3)		    Library Functions Manual		   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	next to	a AG_Button(3)
       which  triggers	the expansion of a 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_Combo area.

       AG_Combo	provides the same functionality	as AG_UCombo(3), but also adds
       support for text	search and arbitrary text input.

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_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 visi-
			      ble.

       AG_COMBO_HFILL	      Expand horizontally in parent container.

       AG_COMBO_VFILL	      Expand vertically	in parent container.

       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-expanded(void)
	   The drop-down menu is now visible.
       combo-collapsed(void)
	   The drop-down menu is now hidden.
       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	  The AG_Tlist(3) displayed by AG_Combo	when expanded,
			  or NULL if collapsed (RO).
       AG_Textbox *tbox	  The input AG_Textbox(3) (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
	     ExpandItems(AG_Event *event)
	     {
		     AG_Combo *com = AG_COMBO_SELF();

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

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

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

	     AG_Combo *com;

	     com = AG_ComboNew(NULL, 0);
	     AG_SetEvent(com, "combo-expanded",	ExpandItems, NULL);
	     AG_SetEvent(com, "combo-selected",	SelectItem, NULL);

       The following code fragment generates a	drop-down  menu	 displaying  a
       tree:

	     static void
	     ExpandTreeItems(AG_Event *event)
	     {
		     AG_Combo *com = AG_COMBO_SELF();
		     AG_TlistItem *it;

		     it	= AG_TlistAdd(com, NULL, "Foo");
		     it->depth = 1;
		     it->flags |= AG_TLIST_HAS_CHILDREN;
		     {
			     it	= AG_TlistAdd(com, NULL, "Bar");
			     it->depth = 2;
			     it	= AG_TlistAdd(com, NULL, "Baz");
			     it->depth = 2;
		     }
	     }

	     AG_Combo *com;

	     com = AG_ComboNew(NULL, 0);
	     AG_SetEvent(com, "combo-expanded",	ExpandTreeItems, NULL);

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

HISTORY
       The AG_Combo widget first appeared in Agar  1.0.	  As  of  Agar	1.6.0,
       AG_COMBO_TREE  is  a deprecated no-op.  "combo-expanded"	and "combo-se-
       lected" appeared	in Agar	1.7.0.	The AG_Tlist(3)	was formerly  pre-gen-
       erated  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	contents  must
       be generated on demand from "combo-expanded".

Agar 1.7		       December	21, 2022		   AG_COMBO(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Combo&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help