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

FreeBSD Manual Pages

  
 
  

home | help
AG_MENU(3)	       FreeBSD Library Functions Manual		    AG_MENU(3)

NAME
     AG_Menu --	agar menu system

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

DESCRIPTION
     The AG_Menu widget	displays a hierarchical	menu composed of items of the
     following types:

     Action items    Selecting the item	causes a specified function to be in-
		     voked, with the specified arguments.  See
		     AG_MenuAction().

     Boolean items   A menu item tied to a variable describing a boolean value
		     (either an	integer, or specific bits in an	integer).  Se-
		     lecting an	active boolean item will toggle	the value.
		     See AG_MenuBool().

     Separators	     A cosmetic	separator, displayed as	a horizontal or	verti-
		     cal bar depending on the display mode.  See
		     AG_MenuSeparator().

     Dynamic items   A dynamically updated menu	item.  The item	itself (possi-
		     bly including child items)	are expected to	be generated
		     by	a specified callback routine.  An example of a dynamic
		     item would	be a submenu displaying	the current contents
		     of	a folder.  See AG_MenuDynamicItem().

     Menu elements can be displayed in text format with	the AG_MenuView	wid-
     get, or in	icon format using AG_Toolbar(3).

     Note: Many	functions of AG_Menu accept fn and fnArgs arguments; see
     AG_Event(3) for details on	event handler functions	in Agar.

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

INITIALIZATION
     AG_Menu * AG_MenuNew(AG_Widget *parent, Uint flags)

     AG_Menu * AG_MenuNewGlobal(Uint flags)

     void AG_MenuExpand(AG_Widget *parentWidget, AG_MenuItem *item, int	x, int
     y)

     void AG_MenuCollapse(AG_MenuItem *item)

     void AG_MenuCollapseAll(AG_Menu *m)

     void AG_MenuSetPadding(AG_Menu *menu, int left, int right,	int top, int
     bottom)

     void AG_MenuSetLabelPadding(AG_Menu *menu,	int left, int right, int top,
     int bottom)

     The AG_MenuNew() function allocates, initializes, and attaches a new
     AG_Menu widget.  Acceptable flags include:

     AG_MENU_HFILL    Expand horizontally in parent (equivalent	to invoking
		      AG_ExpandHoriz(3)).  This	option is recommended.

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

     AG_MENU_EXPAND   Shorthand	for AG_MENU_HFILL|AG_MENU_VFILL.

     The AG_MenuNewGlobal() constructor	creates	a global "application menu".
     The manner	in which application menus are displayed is dependent on the
     underlying	platform and graphics system.  If there	is insufficient	mem-
     ory, or an	application menu is already defined, AG_MenuNewGlobal()	may
     fail returning NULL.

     The AG_MenuExpand() function creates a new	window containing an
     AG_MenuView widget	displaying the menu items under	item.  The optional
     parentWidget argument should point	to some	parent widget or window.  The
     new window	is created at coordinates x, y relative	to parentWidget.  The
     newly created window is also attached to the parent window	of
     parentWidget.

     AG_MenuCollapse() closes the window previously created by AG_MenuExpand()
     for the given menu	item.  AG_MenuCollapseAll() closes all windows gener-
     ated by AG_MenuExpand() for the whole menu	m.

     AG_MenuSetPadding() sets the global padding around	all menu items,	in
     pixels.  AG_MenuSetLabelPadding() sets the	padding	around the text	label
     of	items.	If a parameter is -1, its current value	is preserved.

MENU ITEMS
     AG_MenuItem * AG_MenuNode(AG_MenuItem *parent, const char *text, const
     AG_Surface	*icon)

     AG_MenuItem * AG_MenuAction(AG_MenuItem *parent, const char *text,	const
     AG_Surface	*icon, void (*fn)(AG_Event *), const char *fnArgs, ...)

     AG_MenuItem * AG_MenuActionKb(AG_MenuItem *parent,	const char *text,
     const AG_Surface *icon, AG_KeySym keysym, AG_KeyMod keymod, void
     (*fn)(AG_Event *),	const char *fnArgs, ...)

     AG_MenuItem * AG_MenuDynamicItem(AG_MenuItem *parent, const char *text,
     const AG_Surface *icon, void (*fn)(AG_Event *), const char	*fnArgs, ...)

     AG_MenuItem * AG_MenuDynamicItemKb(AG_MenuItem *parent, const char	*text,
     const AG_Surface *icon, AG_KeySym key, AG_KeyMod kmod, void
     (*fn)(AG_Event *),	const char *fnArgs, ...)

     AG_MenuItem * AG_MenuTool(AG_MenuItem *parent, AG_Toolbar *toolbar, const
     char *text, const AG_Surface *icon, AG_KeySym keysym, AG_KeyMod keymod,
     void (*fn)(AG_Event *), const char	*fnArgs, ...)

     void AG_MenuSetIcon(AG_MenuItem *item, const AG_Surface *su)

     void AG_MenuSetLabel(AG_MenuItem *item, const char	*format, ...)

     void AG_MenuSetLabelS(AG_MenuItem *item, const char *label)

     void AG_MenuSetPollFn(AG_MenuItem *item, void (*fn)(AG_Event *), const
     char *fnArgs, ...)

     void AG_MenuDel(AG_MenuItem *menu)

     void AG_MenuState(AG_MenuItem *item, int state)

     void AG_MenuEnable(AG_MenuItem *item)

     void AG_MenuDisable(AG_MenuItem *item)

     The AG_MenuNode() function	inserts	a new node (no-op) item	displaying the
     given text	and icon (or NULL if none).  Node items	are typically only
     used to attach subitems.

     The AG_MenuAction() function inserts a new	action item displaying the
     given text	and icon (or NULL if none).  When selected, the	item will in-
     voke the specified	event handler function fn.

     The AG_MenuActionKb() variant also	associates the action with the given
     AG_KeySym(3) and modifier.

     The AG_MenuTool() variant also inserts an item into the specified
     AG_Toolbar(3) widget.

     The AG_MenuSetIcon() function sets	the icon associated with a menu	item.
     If	an argument of NULL is given, any existing icon	is removed.

     AG_MenuSetLabel() changes the text	associated with	an existing menu item.
     AG_MenuSetPollFn()	changes	the callback function associated with a	given
     item (previously created with AG_MenuDynamicItem()).

     The AG_MenuDynamicItem() function creates a dynamic menu item.  The spec-
     ified callback routine fn will be invoked repeatedly to update the	menu
     item.  The	AG_Menu	object is passed as AG_SELF(), and pointer to the
     AG_MenuItem structure can be retrieved using AG_SENDER() (see
     AG_Event(3)).  The	callback routine is allowed to directly	modify the
     state member of the AG_MenuItem.  This variable defines the boolean state
     for the specified menu item (0 = disabled,	1 = enabled).  If state	is -1,
     the boolean state is determined from any boolean/flag binding associated
     with the item.  The callback can also change the text label and icon us-
     ing AG_MenuSetLabel() and AG_MenuSetIcon().

     The AG_MenuDel() routine deletes the specified menu item and its sub-
     items.

     The AG_MenuState()	(or its	variants AG_MenuEnable() and AG_MenuDisable())
     request that all subsequently created menu	items are assigned the given
     state.

BOOLEAN	AND BITMASK ITEMS
     AG_MenuItem * AG_MenuBool(AG_MenuItem *, const char *text,	const
     AG_Surface	*icon, int *value, int invert)

     AG_MenuItem * AG_MenuBoolMp(AG_MenuItem *,	const char *text, const
     AG_Surface	*icon, int *value, int invert, AG_Mutex	*mutex)

     AG_MenuItem * AG_MenuIntBool(AG_MenuItem *, const char *text, const
     AG_Surface	*icon, int *value, int invert)

     AG_MenuItem * AG_MenuIntBoolMp(AG_MenuItem	*, const char *text, const
     AG_Surface	*icon, int *value, int invert, AG_Mutex	*mutex)

     AG_MenuItem * AG_MenuInt8Bool(AG_MenuItem *, const	char *text, const
     AG_Surface	*icon, Uint8 *value, int invert)

     AG_MenuItem * AG_MenuInt8BoolMp(AG_MenuItem *, const char *text, const
     AG_Surface	*icon, Uint8 *value, int invert, AG_Mutex *mutex)

     AG_MenuItem * AG_MenuFlags(AG_MenuItem *, const char *text, const
     AG_Surface	*icon, int *value, int flags, int invert)

     AG_MenuItem * AG_MenuFlagsMp(AG_MenuItem *, const char *text, const
     AG_Surface	*icon, int *value, int flags, int invert, AG_Mutex *mutex)

     AG_MenuItem * AG_MenuIntFlags(AG_MenuItem *, const	char *text, const
     AG_Surface	*icon, int *value, int flags, int invert)

     AG_MenuItem * AG_MenuIntFlagsMp(AG_MenuItem *, const char *text, const
     AG_Surface	*icon, int *value, int flags, int invert, AG_Mutex *mutex)

     AG_MenuItem * AG_MenuInt8Flags(AG_MenuItem	*, const char *text, const
     AG_Surface	*icon, Uint8 *value, Uint8 flags, int invert)

     AG_MenuItem * AG_MenuInt8FlagsMp(AG_MenuItem *, const char	*text, const
     AG_Surface	*icon, Uint8 *value, Uint8 flags, int invert, AG_Mutex *mutex)

     AG_MenuItem * AG_MenuInt16Flags(AG_MenuItem *, const char *text, const
     AG_Surface	*icon, Uint16 *value, Uint16 flags, int	invert)

     AG_MenuItem * AG_MenuInt16FlagsMp(AG_MenuItem *, const char *text,	const
     AG_Surface	*icon, Uint16 *value, Uint16 flags, int	invert,	AG_Mutex
     *mutex)

     AG_MenuItem * AG_MenuInt32Flags(AG_MenuItem *, const char *text, const
     AG_Surface	*icon, Uint32 *value, Uint32 flags, int	invert)

     The AG_Menu*Bool()	functions create a new item that binds to the given
     boolean variable.	If the invert parameter	is non-zero, the actual	value
     is	inverted.

     The AG_Menu*Flags() functions create a new	item controlling one or	more
     bits inside an integer value.  The	flags argument specifies the bitmask.
     If	invert is non-zero, the	bits are inverted.

     The AG_Menu*BoolMp() and AG_Menu*FlagsMp()	variants accept	a AG_Mutex *
     argument specifying a mutex to acquire prior to reading or	writing	the
     data.

OTHER ITEMS
     void AG_MenuSeparator(AG_MenuItem *item)

     void AG_MenuSection(AG_MenuItem *item, const char *format,	...)

     void AG_MenuSectionS(AG_MenuItem *item, const char	*text)

     The AG_MenuSeparator() function inserts a horizontal menu separator.

     AG_MenuSection() creates a	non-selectable item displaying the given text.

POPUP MENUS
     AG_PopupMenu * AG_PopupNew(AG_Widget *widget)

     void AG_PopupShow(AG_PopupMenu *pm)

     void AG_PopupShowAt(AG_PopupMenu *pm, int x, int y)

     void AG_PopupHide(AG_PopupMenu *pm)

     void AG_PopupDestroy(AG_Widget *widget, AG_PopupMenu *pm)

     The AG_PopupNew() function	creates	a new popup menu and associates	it
     with the specified	widget.	 This association will cause the popup menu to
     be	automatically freed when the given widget is destroyed.

     Once a popup menu is created, new items can be inserted using the root
     member of the AG_PopupMenu	structure as parent.

     AG_PopupShow() displays the popup menu at the current mouse coordinates.
     AG_PopupShowAt() accepts global (view) coordinates.  AG_PopupHide() hides
     the popup menu from the user.

     AG_PopupDestroy() detaches	the specified popup menu from its associated
     widget, and releases its allocated	resources.  This function is automati-
     cally invoked whenever a widget is	destroyed.

EVENTS
     The AG_Menu widget	does not generate any event.

BINDINGS
     The AG_Menu widget	does not provide any binding.

STRUCTURE DATA
     For the AG_Menu object:

     AG_MenuItem *root	    The	root menu item (read-only).

     AG_MenuItem *itemSel   The	currently selected top-level item (read-only).
			    Top-level items are	attached directly to root.

     int selecting	    Selection is in progress if	set to 1 (read-only).

     For the AG_MenuItem structure:

     char *text			 Displayed text	for the	menu item (read-only,
				 set by	AG_MenuSetLabel()).

     AG_Surface	*iconSrc	 The AG_Surface(3) of the menu icon, or	NULL
				 (read-only, set by AG_MenuSetIcon()).

     int value			 The boolean state of the item,	used by	de-
				 fault.	 If the	boolean	state was bound	to an-
				 other variable	(e.g., using AG_MenuBool() or
				 AG_MenuSetIntBool()), this value is ignored.

     int state			 Make item clickable (1) or disabled (0).

     int (*stateFn)(AG_Event *)	 Evaluate function to determine	if item	is ac-
				 tive.	Overrides the state flag.

     AG_Menu *pmenu		 Back pointer to the parent AG_Menu (read-
				 only).

EXAMPLES
     The following code	fragment creates a popup menu with a disabled item:

	   AG_PopupMenu	*pm;
	   AG_MenuItem *mi;

	   pm =	AG_PopupNew(myParentWidget);
	   AG_MenuAction(pm->root, "Copy", NULL, DoCopy, NULL);
	   mi =	AG_MenuAction(pm->root,	"Paste", NULL, DoPaste,	NULL);
	   mi->state = (myClipboard->contents >	0);

     The following code	fragment creates a popup menu with a dynamically de-
     termined "disabled" state:

	   static int
	   PasteActive(AG_Event	*event)
	   {
		   Clipboard *C	= AG_PTR(1);
		   return (C->contents > 0);
	   }

	   AG_PopupMenu	*pm;
	   AG_MenuItem *mi;

	   pm =	AG_PopupNew(myParentWidget);
	   AG_MenuAction(pm->root, "Copy", NULL, DoCopy, NULL);
	   mi =	AG_MenuAction(pm->root,	"Paste", NULL, DoPaste,	NULL);
	   mi->stateFn = AG_SetIntFn(pm->menu, PasteActive, "%p", myClipboard);

     The following code	fragment associates a menu with	an AG_Toolbar(3).
     Buttons and menu entries are created for the same actions.

	   AG_Toolbar *toolbar;
	   AG_Menu *menu;
	   AG_MenuItem *item;

	   toolbar = AG_ToolbarNew(win,	AG_TOOLBAR_HORIZ, 1, 0);
	   menu	= AG_MenuNew(win, 0);
	   item	= AG_MenuNode(menu->root, "File", NULL);
	   {
		   AG_MenuToolbar(item,	toolbar);
		   AG_MenuAction(item, "Load", NULL, LoadFile, NULL);
		   AG_MenuAction(item, "Save", NULL, SaveFile, NULL);
		   AG_MenuToolbar(item,	NULL);
	   }

     The following code	fragment creates a menu	with an	action item, a boolean
     item and two bitmask items.

	   Uint16 flags	= 0;
	   #define FOO_FLAG 0x01
	   #define BAR_FLAG 0x02

	   void
	   SayHello(AG_Event *event)
	   {
		   char	*s = AG_STRING(1);
		   AG_TextMsg(AG_MSG_INFO, "Hello, %s!", s);
	   }

	   void
	   QuitApplication(AG_Event *event)
	   {
		   AG_Quit();
	   }

	   ...

	   AG_Menu *menu = AG_MenuNew(win);
	   AG_MenuItem *item = AG_MenuNode(menu->root, "File", NULL);
	   {
		   AG_MenuInt16Flags(item, "Foo", NULL,	&flags,	FOO_FLAG, 0);
		   AG_MenuInt16Flags(item, "Bar", NULL,	&flags,	BAR_FLAG, 0);
		   AG_MenuAction(item, "Say hello", NULL,
		       SayHello, "%s", "world");
		   AG_MenuAction(item, "Quit", NULL,
		       QuitApplication,	NULL);
	   }

SEE ALSO
     AG_Button(3), AG_Event(3),	AG_Intro(3), AG_KeySym(3), AG_Surface(3),
     AG_Tlist(3), AG_Toolbar(3), AG_Widget(3), AG_Window(3)

HISTORY
     The AG_Menu widget	first appeared in Agar 1.0.

FreeBSD	13.0			 May 30, 2005			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INITIALIZATION | MENU ITEMS | BOOLEAN AND BITMASK ITEMS | OTHER ITEMS | POPUP MENUS | EVENTS | BINDINGS | STRUCTURE DATA | EXAMPLES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Menu&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help