[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

	CreateMenusA -- allocate and fill out a menu structure. (V36)
	CreateMenus -- varargs stub for CreateMenus(). (V36)

	menu = CreateMenusA(newmenu, tagList)
	D0                  A0       A1

	struct Menu *CreateMenusA(struct NewMenu *, struct TagItem *);

	menu = CreateMenus(newmenu, firsttag, ...)

	struct Menu *CreateMenus(struct NewMenu *, Tag, ...);

	CreateMenusA() allocates and initializes a complete menu
	structure based on the supplied array of NewMenu structures.
	Optionally, CreateMenusA() can allocate and initialize a complete
	set of menu items and sub-items for a single menu title.  This
	is dictated by the contents of the array of NewMenus.

	newmenu - pointer to an array of initialized struct NewMenus.
	tagList - pointer to an array of tags providing optional extra
		  parameters, or NULL.

	GTMN_FrontPen (UBYTE) - Pen number to be used for menu text.
	    (Under V39 and higher, this tag also exists for LayoutMenusA()
	    and LayoutMenuItemsA()).  (defaults to zero).
	GTMN_FullMenu (BOOL) - Requires that the NewMenu specification
	    describes a complete menu strip, not a fragment.  If a fragment
	    is found, CreateMenusA() will fail with a secondary error of
	    GTMENU_INVALID.  (defaults to FALSE). (V37)
	GTMN_SecondaryError (ULONG *) - Supply a pointer to a NULL-initialized
	    ULONG to receive a descriptive error code.  Possible values:
	    GTMENU_INVALID - NewMenu structure describes an illegal
	        menu.  (CreateMenusA() will fail with a NULL result).
	    GTMENU_TRIMMED - NewMenu structure has too many menus, items,
	        or subitems (CreateMenusA() will succeed, returning a
	        trimmed-down menu structure).
	    GTMENU_NOMEM - CreateMenusA() ran out of memory.

	menu - pointer to the resulting initialized menu structure (or
              the resulting FirstItem), with all the links for menu items
              and subitems in place.
              The result will be NULL if CreateMenusA() could not allocate
              memory for the menus, or if the NewMenu array had an
              illegal arrangement (eg. NM_SUB following NM_TITLE).
              (see also the GTMN_SecondaryError tag above).

	The strings you supply for menu text are not copied, and must
	be preserved for the life of the menu.
	The resulting menus have no positional information.  You will
	want to call LayoutMenusA() (or LayoutMenuItemsA()) to supply that.
	CreateMenusA() automatically provides you with a UserData field
	for each menu, menu-item or sub-item.  Use the GTMENU_USERDATA(menu)
	or GTMENUITEM_USERDATA(menuitem) macro to access it.

	Prior to V39, if you put images into menus using IM_ITEM
	or IM_SUB for a NewMenu->nm_Type, the image supplied had to
	be an ordinary struct Image.  Starting with V39, you can use
	boopsi images.

	LayoutMenusA(), FreeMenus(), gadtools.h/GTMENU_USERDATA(),

[Back to Amiga Developer Docs]