Docs » Autodocs » gadtools.library » CreateMenusA
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.
(V37)
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, gadtools.h/GTMENUITEM_USERDATA
|
