[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 a TagItem list.

    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.

    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.

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

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

[Back to Amiga Developer Docs]