| MenuKey | Function (ROM Call 0x39)

menus.h

short MenuKey (HANDLE ExecHandle, short KeyCode);

Activates a toolbar menu by processing a key press.

MenuKey is the heart of all toolbar menus. It activates the menu associated with the handle ExecHandle, where ExecHandle is a handle returned from MenuBegin (not from MenuNew). The parameter KeyCode is the code of the key associated with the menu item (toolbox) which will be activated. If this toolbox has a pulldown menu assigned to it (DMF_TOP_SUB), it will be opened, and the user can navigate through the menu using the arrow keys. If the toolbox has no pulldown menu, MenuKey returns immediately. A typical method of calling MenuKey is to pass a result of the ngetchx function (which waits for a keypress and returns the key code) to the parameter KeyCode:

    result = MenuKey (exec_handle, ngetchx ());

MenuKey returns the following values (as far as I know; maybe other return values also exist):

- M_NOITEM, if the user pressed ESC while the menu was active, or if the code of a disabled toolbox (see MenuTopStat) was passed to MenuKey;
- M_NOTMENUKEY, if a wrong key code was passed to it (i.e. a key code which is not associated with any menu item);
- a positive value, if the user selects a menu item normally. In this case, the return value will be the identification number (ID) of the selected menu item (see MenuAddText).

Note that this approach is very flexible, because the actual reading of the keypress is done in the user program, so it allows various ways of "hooking" into the "heart" of the menu. Most importantly, the user program can decide which keys belong to the menu.
This routine may cause heap compression.
Here is an example of defining a menu and using MenuKey to activate it (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: FKeyI_H, HeapAllocESTACK, HeapFree, BitmapGet, BitmapPut, BitmapSize, CalcBitmapSize, DrawChar, DrawClipRect, DrawFkey, DrawLine, DrawMultiLines, DrawPix, DrawStr, DrawStrWidth, FontSetSys, PortRestore, RestoreScrState, SaveScrState, ScrRect, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip, alphaLockOff, alphaLockOn, GKeyIn, restoreAlphaLock, memset, ST_eraseHelp, ST_helpMsg, strlen, CU_cursorState, CU_restore, CU_stop, XR_stringPtr, CTypeTable, ROM Call 0x3EA, ROM Call 0x41E, ROM Call 0x420, ROM Call 0x422
Used by: cmd_toolbar, EV_defaultHandler, handleVarLinkKey

See also: MenuBegin