[Contents] [index] [Help] [Retrace] [browse <] [Browse >]

The createmenus() function takes an array of newmenus and creates a set of
initialized and linked Intuition menu, menuitem, image and intuitext
structures, that need only to be formatted before being used.  Like the
other tag-based functions, there is a createmenusa() call that takes a
pointer to an array of tagitems and a createmenus() version that expects
to find its tags on the stack.

    struct Menu *CreateMenusA( struct NewMenu *newmenu,
                               struct TagItem *taglist );
    struct Menu *CreateMenus( struct NewMenu *newmenu, Tag tag1, ... );

The first argument to these functions, newmenu, is a pointer to an array
of newmenu structures as described earlier.  the tag arguments can be any
of the following items:

GTMN_FrontPen (ULONG)
    The pen number to use for menu text and separator bars.  The default
    is zero.

GTMN_FullMenu (BOOL)
    (New for V37, ignored under V36).  This tag instructs createmenus()
    to fail if the supplied newmenu structure does not describe a
    complete menu structure.  this is useful if the application does not
    have direct control over the NewMenu description, for example if it
    has user-configurable menus.  The default is FALSE.

GTMN_SecondaryError (ULONG *)
    (New for V37, ignored under V36).  This tag allows createmenus() to
    return some secondary error codes.  Supply a pointer to a
    NULL-initialized ULONG, which will receive an appropriate error code
    as follows:

    GTMENU_INVALID
        Invalid menu specification.  For instance, a sub-item directly
        following a menu-title or an incomplete menu.  createmenus()
        failed in this case, returning NULL.

    GTMENU_NOMEM
        Failed for lack of memory.  createmenus() returned null.

    GTMENU_TRIMMED
        The number of menus, items or sub-items exceeded the maximum
        number allowed so the menu was trimmed.  In this case,
        createmenus() does not fail but returns a pointer to the trimmed
        menu structure.

    NULL
        If no error was detected.

createmenus() returns a pointer to the first menu structure created, while
all the menuitem structures and any other menu structures are attached
through the appropriate pointers.  If the newmenu structure begins with an
entry of type nm_item or im_item, then createmenus() will return a pointer
to the first MenuItem created, since there will be no first Menu
structure.  If the creation fails, usually due to a lack of memory,
CreateMenus() will return NULL.

Starting with V37, GadTools will not create any menus, menu items or
sub-items in excess of the maximum number allowed by Intuition.  Up to 31
menus may be defined, each menu with up to 63 items, each item with up to
31 sub-items.  See the "intuition menus" chapter for more information on
menus and their limitations.  If the newmenu array describes a menu that
is too big, createmenus() will return a trimmed version.
GTMN_SecondaryError can be used to learn when this happens.

Menus need to be added to the window with Intuition's setmenustrip()
function.  Before doing this, they must be formatted with a call to
layoutmenus().