NAME
    CreateMenusA -- Allocate and fill out a menu structure. (V36)
    CreateMenus -- Varargs stub for CreateMenus(). (V36)

SYNOPSIS
    menu = CreateMenusA(newmenu, taglist)
    D0                  A0       A1

    struct menu *createmenusa(struct newmenu *, struct tagitem *);

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

    struct menu *createmenus(struct newmenu *, tag, ...);

FUNCTION
    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.

INPUTS
    newmenu - Pointer to an array of initialized struct NewMenus.
    taglist - Pointer to a tagitem list.

TAGS
    GTMN_FrontPen (UBYTE) - Pen number to be used for menu text.
        (defaults to zero).
    GTMN_FullMenu (BOOL) - (GadTools V37 and higher only)
        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).
    GTMN_SecondaryError (ULONG *) - (GadTools V37 and higher only)
        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.

RESULT
    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).

EXAMPLE

NOTES
    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.

BUGS
    At present, if you put images into menus using IM_ITEM
    or IM_SUB for a NewMenu->Type, the image you supply must
    be an ordinary struct image.  you may not use a 'custom
    image' (eg. one obtained from a boopsi image-class).

SEE ALSO
    layoutmenusa(), freemenus(), gadtools.h/gtmenu_userdata(),
    gadtools.h/GTMENUITEM_USERDATA()