MenuNew Function (ROM Call 0x43)

menus.h

HANDLE MenuNew (short Flags, short Width, short Height);

Creates a new toolbar menu.

MenuNew allocates memory for a new toolbar menu (i.e. a menu which looks like the main menu of the home screen), initializes the allocated block with the necessary structures, and returns a handle to it (or H_NULL in case of an error). You can later free the memory by calling HeapFree, but note that this is done automatically if you use the MBF_HMENU flag when calling the MenuBegin function. Width and Height are the width and the height of the menu in pixels. Passing 0 means that the width or height should be calculated automatically; however, AMS 1.xx simply uses the default values in this case. Values which are too large are converted to the largest possible values; for the height this is a value of 18. If the cumulated width of the items in the menu is greater than the available width of the menu, the menu items will scroll left or right if necessary.

This routine may cause heap compression.

The parameter Flags contains various flags defined in the enum MenuFlagsEnum. TI recommends passing 0, but the TIOS mainly passes MF_TOOLBOX when calling this routine. This parameter is copied to the Flags field of the menu structure (see MenuPopup for info about this structure).

The method for creating menus on AMS 2.00 or later which TI proposes is as follows:

  1. Create an empty, dynamic menu structure with MenuNew or MenuLoad.
  2. Build the menu with DynMenuAdd or DynMenuChange using the handle returned by MenuNew or MenuLoad (each of these routines returns H_NULL if not enough memory, or check MenuFlags when done with all of the additions/changes).
  3. Call MenuBegin setting the MBF_HMENU flag and passing the handle returned by MenuNew or MenuLoad as the argument after the Flags parameter (MenuBegin has a variable number of arguments). NULL can be passed as the pointer to the menu structure (since the dereferenced handle points to this structure). (If interested, see MenuPopup for more informations on menu structures.) This will lock the handle returned from MenuNew and save it.
  4. Using the handle returned from MenuBegin (this is a separate handle!), you may then call all of the normal menu functions (MenuCheck, MenuKey, MenuOn, MenuTopStat, MenuTopSelect, etc.).
  5. When done with the menu, call MenuEnd on the handle returned from MenuBegin. This will free the handle returned from MenuBegin as well as the handle returned from MenuNew.
Do not forget that once you call MenuBegin, you may not unlock the handle returned from MenuNew, nor call DynMenuAdd or DynMenuChange.

It might also be useful for you to have the following information:

 TI-89TI-92
Maximum menu width (in pixels)160240
Top-level font
(as defined in the Fonts enum)
F_4x6F_6x8
Sub-level font
(as defined in the Fonts enum)
F_6x8F_6x8


Uses: HeapAlloc, memset
Used by: cmd_custom, cmd_toolbar


See also: MenuBegin, MenuKey, MenuLoad, DynMenuAdd, DynMenuChange, MenuAddText, MenuAddIcon