MenuBegin Function (ROM Call 0x36)

menus.h

HANDLE MenuBegin (const void *MenuPtr, short x, short y, unsigned short Flags, ...);

Displays a toolbar menu and creates a new structure which is used for executing the menu.

MenuBegin shows the toolbar menu pointed to by MenuPtr on the screen. The top-left corner of the menu will be at the position (xy); the coordinates are absolute screen coordinates. x, y, or both may also have the special value CENTER, which tells MenuBegin to center the menu in a particular dimension.

Note that this function does not use a handle if called in a normal fashion. Instead, it needs a pointer to the actual menu structure. So you must use HLock to lock and dereference the handle before using this function (locking is highly recommended because heap compression may occur):

exec_handle = MenuBegin (HLock (handle), x, y, Flags);
A second way which is almost equal to the one above but only works on AMS 2.00 or higher is to pass NULL to MenuPtr and MBF_HMENU to Flags. Then the optional parameter after Flags will take the handle instead:
exec_handle = MenuBegin (NULL, x, y, Flags | MBF_HMENU, handle);
But note that in this case, the handle will be freed when MenuEnd is called.

Alternatively (but only if you are an expert), you can pass a pointer to a pre-filled static menu structure to MenuPtr (like the TIOS usually does). Using this approach you can save a lot of memory. See MenuPopup for more info about this.

MenuBegin does not activate the menu. Instead, it creates yet another structure which is necessary to execute the menu, and returns the handle to it (or H_NULL in case of an error, i.e. if there was not enough memory to allocate the new structure). To activate the menu, you must call MenuKey with this handle.

The Flags parameter contains a combination of the following flags, defined in the enum MenuBeginFlags:

MBF_WITHICON Reserve extra space in memory in order to display menus with icons.
MBF_REDEF Allow for the top-level items (special text/icon combination) to be redefined with the MenuTopRedef function.
Note: The only way to create redefinable menu items is to use a pre-filled menu structure.
MBF_SYS_ALLOC Unknown for the moment (do not use).
MBF_MAX_MENU_WIDTH AMS 2.00 or higher: The parameter after Flags should be a short integer representing the maximum field width to use for the menu (by default it is the screen width). This maximum field width is only used if the menu width is calculated automatically (i.e. the width was set to 0). If you wish to use both MAX_MENU_WIDTH and MBF_HMENU at the same time, see below.
MBF_STRIKEOUT AMS 2.00 or higher: Use strikeout (line drawn through text or icon fields) instead of grayed items to indicate disabled menu items.
MBF_HMENU AMS 2.00 or higher: The parameter after Flags should be the handle of a dynamically created menu. If this flag is used, the parameter MenuPtr is ignored and should be set to NULL. The handle is locked and dereferenced and used instead of MenuPtr. The handle is saved internally, and calling MenuEnd on the handle returned by MenuBegin will free this handle. If you wish to use both MAX_MENU_WIDTH and MBF_HMENU at the same time, see below.
MBF_NO_DRAWTOP AMS 2.00 or higher: Set up the menu-draw structure and return a handle to it, but do not draw the menu. You have to call MenuOn to draw it.

If both MAX_MENU_WIDTH and MBF_HMENU are set, the first parameter after Flags represents the maximum menu width, and the second parameter after Flags represents the handle to a dynamic menu.

This routine may cause heap compression.


Uses: MenuOn, HeapAlloc, HeapLock, CalcBitmapSize, DrawStrWidth, memset, ROM Call 0x41E
Used by: cmd_toolbar, EV_defaultHandler, handleVarLinkKey, CustomBegin