MenuAddText Function (ROM Call 0x41)

menus.h

HANDLE MenuAddText (HANDLE Handle, short ParentID, const char *Text, short ID, short Flags);

Adds a new text item in a toolbar menu.

MenuAddText adds the text Text to the toolbar menu associated with the handle Handle. The text added first will be the first option in the menu, the text added second will be the second option, and so on.

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

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

MenuAddText returns H_NULL in case of an error, otherwise it returns Handle. 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). MenuAddText may cause heap compression.

Although the TIOS menu system allows for toolbar menus with associated pulldown menus which have their own submenus (i.e. more than one level of nesting), it is not possible to create such menus in AMS 1.xx using this command. If you really want more levels of nesting and need to stay compatible, you need to use pre-filled static structures and pass them directly to the MenuBegin function (see MenuPopup for more info). But, note that this is somewhat complicated.

The Flags parameter contains one of the following flags, defined in the enum DynMenuFlags:

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 AMS 2.00 or higher: 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.


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

// 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);
  MenuAddText (menu_handle, 0, "First", 1, DMF_TOP_SUB);
  MenuAddText (menu_handle, 1, "Subitem 1.1", 5, DMF_CHILD_SUB);
  MenuAddText (menu_handle, 5, "Subitem 1.1.1", 8, DMF_CHILD_SUB);
  MenuAddText (menu_handle, 5, "Subitem 1.1.2", 9, DMF_CHILD);
  MenuAddText (menu_handle, 8, "Subitem 1.1.1.1", 10, DMF_CHILD);
  MenuAddText (menu_handle, 1, "Subitem 1.2", 6, DMF_CHILD);
  MenuAddText (menu_handle, 0, "Second", 2, DMF_TOP_SUB);
  MenuAddText (menu_handle, 2, "Subitem 2.1", 7, DMF_CHILD);
  MenuAddText (menu_handle, -1, "Third", 3, DMF_TOP);
  MenuAddText (menu_handle, -1, "Fourth", 4, 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: DynMenuAdd
Used by: cmd_custom, cmd_toolbar, MO_modeDialog, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x486


See also: MenuNew, MenuLoad, DynMenuAdd, DynMenuChange, MenuAddIcon