DynMenuAdd Function (ROM Call 0x3F1)

AMS 2.00 or higher menus.h

HANDLE DynMenuAdd (HANDLE Handle, short ParentID, const void *Data, short ID, unsigned short Flags);

Adds a new entry to a dynamic menu.

DynMenuAdd adds a new entry to the dynamic toolbar menu associated with the handle Handle, which must be a handle created by MenuNew or MenuLoad. The entry added first will be the first option in the menu, the entry added second will be the second option, and so on. Each new entry (pointed by Data) can either be a text, an ICON structure, or a BITMAP structure, depending on the parameter Flags.

This function is similar to MenuAddText and MenuAddIcon, except that it is available only in AMS 2.00 and later (i.e. you have to set MIN_AMS in TIGCC to 200 or higher). This function also offers a new feature: the use of bitmaps in menus. In fact, TI says that MenuAddText and MenuAddIcon are just older ways to do the same things, so DynMenuAdd can fully replace those functions if you plan to run your program only on AMS 2.00 or later.

ID is the identification number of the item. It is used to identify the item in many other functions; for example it will later be returned by the MenuKey function if the user selects this menu item. You may also be able to change this new entry using the ID number and the function DynMenuChange. Moreover, this value can be used by a child entry to identify its parent. If ID equals 0, the TIOS will generate the ID automatically (1 for the first menu entry, 2 for the second entry, etc.). The legal range for ID is 1 to 4095. If ID is greater than 4095, it will be truncated (ANDed with 0x0FFF).

Note: If you are adding to a prefilled static menu (i.e. written in your source code and loaded using MenuLoad), do not use the range 0x0F00 to 0x0FFF (i.e. do not use an ID greater than 3839).

DynMenuAdd returns H_NULL in case of an error, otherwise it returns Handle. An error occurs if the system runs out of memory, or if there is an error in the parameters (ParentID not found, ParentID found but it was not a possible parent, or maximum number of items in a menu exceeded). If there is an error adding the new entry, the MF_ERROR flag in the menu structure is set (you can use MenuFlags to get this flag, but do not confuse menu structure flags such as MF_ERROR and the parameter Flags in MenuAddText which gives the type of entry). DynMenuAdd may cause heap compression.

The parameter ParentID must be set to 0 if this is a new top-level entry (i.e. if this entry has no parent), or to the ID of the parent entry if this entry is a child (i.e. this is an item in a pulldown menu). Note that if this entry is at top level, ParentID can also be set to -1, which means it has no child. (For some reason, this seems to be the only way to prevent any other entry to be a child of this one, as the DMF_TOP flag still allows child entries.)

The Flags parameter, defined in the enum DynMenuFlags, must contain one of the flags described in the first following table, bitwise ORed with one of the flags described in the second table:

DMF_TEXT The parameter Data points to a text string.
DMF_ICON The parameter Data points to an ICON structure.
DMF_BITMAP The parameter Data points to a BITMAP structure.


DMF_TOP New top-level entry that cannot be a parent.
Note that this flag does not seem to prevent any other entry to be a child of this one (i.e. when this flag is set in an entry, that entry can still be a parent). To prevent this, please set -1 for the ParentID parameter as well as setting this flag.
DMF_TOP_SUB New top-level entry that can have children.
DMF_CHILD Child entry whose parent is the one specified by the parameter ParentID.
This child entry cannot be the parent of another entry (i.e. no submenu available for this entry).
Note: The parent specified by ParentID should have the DMF_TOP_SUB or the DMF_CHILD_SUB flag set.
DMF_CHILD_SUB Child entry whose parent is the one specified by the parameter ParentID.
This child entry can be the parent of another entry (i.e. submenus are available for this entry).
With this option, you can create many sublevels of nesting.
Note: The parent specified by ParentID should have the DMF_TOP_SUB or the DMF_CHILD_SUB flag set.

If you forget to give a DMF_TEXT, DMF_ICON or DMF_BITMAP flag, DynMenuAdd will automatically consider Data to point to a text string.

Here is an example for this function (called "Menu Example 2"):

// A simple menu example, with several submenus

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define RETURN_VALUE          // Return a Value
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  HANDLE menu_handle = MenuNew (2, 240, 18);
  DynMenuAdd (menu_handle, 0, "First", 1, DMF_TEXT | DMF_TOP_SUB);
  DynMenuAdd (menu_handle, 1, "Subitem 1.1", 5, DMF_TEXT | DMF_CHILD_SUB);
  DynMenuAdd (menu_handle, 5, "Subitem 1.1.1", 8, DMF_TEXT | DMF_CHILD_SUB);
  DynMenuAdd (menu_handle, 5, "Subitem 1.1.2", 9, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, 8, "Subitem 1.1.1.1", 10, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, 1, "Subitem 1.2", 6, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, 0, "Second", 2, DMF_TEXT | DMF_TOP_SUB);
  DynMenuAdd (menu_handle, 2, "Subitem 2.1", 7, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, -1, "Third", 3, DMF_TEXT | DMF_TOP);
  DynMenuAdd (menu_handle, -1, "Fourth", 4, DMF_TEXT | DMF_TOP);
  HANDLE exec_handle = MenuBegin (NULL, 0, 0, MBF_HMENU, menu_handle);
  short result;
  do {
    result = MenuKey (exec_handle, ngetchx ());
  } while (result == M_NOTMENUKEY);
  MenuEnd (exec_handle);
  MenuUpdate ();
  push_shortint (result);
}


Uses: HeapRealloc, CalcBitmapSize, memcpy, memmove, memset, strlen, strncpy
Used by: MenuAddIcon, MenuAddText, PopupAddText, EV_defaultHandler, EV_quit


See also: MenuNew, MenuLoad, DynMenuChange