CreateMenusA

allocate and fill out a menu structure. (V36)

CreateMenus

varargs stub for CreateMenus(). (V36)

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()