The <menus.h> Header File

Routines for creating popup and toolbar menus

Functions

DynMenuAdd
Adds a new entry to a dynamic menu.
DynMenuChange
Changes an entry in a dynamic menu.
FKeyI_H
Returns the corresponding menu item for a function key.
MenuAddIcon
Adds a new icon item in a toolbar menu.
MenuAddText
Adds a new text item in a toolbar menu.
MenuBegin
Displays a toolbar menu and creates a new structure which is used for executing the menu.
MenuCheck
Checks/unchecks or returns the state of an item in a pulldown menu.
MenuEnd
Deallocates an executable menu structure and removes the menu from the screen.
MenuFlags
Return the flag word for a dynamic menu/popup structure.
MenuGetTopRedef
Gets the index of a toolbox icon.
MenuItemDef
Returns a pointer to the data of a menu item.
MenuKey
Activates a toolbar menu by processing a key press.
MenuLoad
Begins a dynamically created menu using a prefilled static menu as the starting point.
MenuNew
Creates a new toolbar menu.
MenuOff
Disables a toolbar menu.
MenuOn
Redraws a toolbar menu.
MenuPopup
Executes a popup menu given a pointer to a popup menu structure.
MenuSubStat
Changes the state (enabled/disabled) of an item in a pulldown menu.
MenuTopRedef
Redefines a toolbox icon.
MenuTopSelect
Emphasizes a toolbox.
MenuTopStat
Changes the state (enabled/disabled) of a toolbox.
MenuUpdate
Draws the default home screen menu.
PopupAddText
Adds a new text item in a popup menu.
PopupBegin
Creates a new popup menu with checkmarks features.
PopupBeginDo
Executes a dynamically allocated popup using a menu-draw handle.
PopupClear
Clears a popup or toolbar menu structure.
PopupDo
Executes a popup menu.
PopupNew
Creates a new popup menu.
PopupText
Returns a pointer to the text of a popup menu item.
QMenuTopSelect
Returns the currently selected top-level menu item.
VarCreateFolderPopup
Creates a popup menu containing a list of all folders.

Constants

CENTER
A constant to describe a centered position for dialogs.
H_NULL
A null-handle value.
NULL
A null-pointer value.

Predefined Types

BITMAP
A structure for defining a bitmap.
Bool
An enumeration to describe true or false values.
CommonKeys
An enumeration for describing common key codes.
DynMenuFlags
An enumeration for describing possible flags associated to dynamic menu entries.
HANDLE
Represents a handle associated with an allocated memory block.
ICON
A structure which describes an icon.
ItemTypes
An enumeration for describing item types in menus.
MenuBeginFlags
An enumeration for describing possible flags passed to MenuBegin.
MenuCheckCmds
An enumeration for describing possible commands for the MenuCheck function.
MenuFlagsEnum
An enumeration for describing possible flags contained in a dynamic menu.
MenuKeyValues
Contains predefined return values of MenuKey.
pICON
A pointer to the ICON scructure.
VCFPFlags
Describes possible flags for VarCreateFolderPopup.

DynMenuAdd

AMS 2.00 or higher

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);
}

See also: MenuNew, MenuLoad, DynMenuChange


DynMenuChange

AMS 2.00 or higher

HANDLE DynMenuChange (HANDLE Handle, short ID, const void *NewData, unsigned short Flags);

Changes an entry in a dynamic menu.

DynMenuChange replaces an entry created with DynMenuAdd, MenuAddText, or MenuAddIcon in the dynamic toolbar menu associated with the handle Handle with a new entry (pointed to by NewData). Handle must be a handle created by MenuNew or MenuLoad. The new entry pointed by NewData can either be a text, an ICON structure, or a BITMAP structure, depending on the parameter Flags. ID is the identification number of the existing item you wish to change.

DynMenuChange 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. If there is an error replacing the 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 with the parameter Flags in DynMenuChange which gives the type of entry). DynMenuChange may cause heap compression.

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

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

See also: MenuNew, MenuLoad, DynMenuAdd


FKeyI_H

AMS 2.02 or higher

short FKeyI_H (HANDLE ExecHandle, short Key);

Returns the corresponding menu item for a function key.

FKeyI_H returns the corresponding index to the function key given in Key of the menu associated with the ExecHandle handle, or returns M_NOTMENUKEY for function keys not used in the given menu. The ExecHandle handle should have been returned from MenuBegin.

Key should be a function key (i.e. KEY_Fx) given in the enum CommonKeys. KEY_F1 will return 0 for the first top-level entry if it exists, KEY_F2 will return 1 for the second top-level entry if it exists, and so on.

FKeyI_H can be useful in combination with MenuKey.

See also: MenuBegin, MenuKey


MenuAddIcon

HANDLE MenuAddIcon (HANDLE Handle, short ParentID, const void *Icon, short ID, short Flags);

Adds a new icon item in a toolbar menu.

MenuAddIcon is very similar to MenuAddText, except instead of a text, the added menu item will consist of an icon. The icon is a 16x16 bitmap structure given as a 16-word group of bits, and parameter Icon is the pointer to it. This pointer is usually of type pICON (pointer to the ICON structure). All other parameters are explained in the MenuAddText function.

Note: It seems that it is possible to add items with icons instead of text to popup menus, too (not only to toolbar menus).

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


MenuAddText

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);
}

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


MenuBegin

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.


MenuCheck

short MenuCheck (HANDLE ExecHandle, short ID, unsigned short Cmd);

Checks/unchecks or returns the state of an item in a pulldown menu.

MenuCheck checks/unchecks or returns the state of the check mark of the pulldown submenu item identified by ID (see MenuAddText for more details about item IDs). ExecHandle is a handle returned from the MenuBegin function, not from MenuNew.

If Cmd is set to MC_STATUS, MenuCheck returns the status of the check mark (zero: not checked, nonzero: checked). Otherwise it returns TRUE on success (i.e. item was found) and FALSE on failure.

The Cmd parameter must be one of the following values, defined in the enum MenuCheckCmds:

MC_CHECK Display a check mark next to the menu item.
MC_UNCHECK AMS 2.00 or higher: Remove the check mark.
MC_STATUS Return the status of the check mark (zero: not checked, nonzero: checked).
MC_FLIP Invert the status of the check mark.

See also: MenuBegin


MenuEnd

void MenuEnd (HANDLE ExecHandle);

Deallocates an executable menu structure and removes the menu from the screen.

MenuEnd deletes the structure needed for executing the toolbar menu (such a structure is created using MenuBegin), and removes the menu from the screen by filling the menu area with blank pixels (except if the MBF_NO_DRAWTOP flag was passed to MenuBegin). Note that it never restores the background which was present before the menu was drawn; you must do this manually. If the menu was drawn at the top of the screen (as usually), calling MenuUpdate may help. Also note that MenuEnd does not remove the structure created using MenuNew unless you used the MBF_HMENU flag; you must call HeapFree to remove it.

See also: MenuBegin, MenuKey


MenuFlags

AMS 2.00 or higher

short MenuFlags (HANDLE Handle);

Return the flag word for a dynamic menu/popup structure.

MenuFlags returns the flags stored in a dynamic menu structure (see MenuPopup for more information on menu structures). For the moment, the only useful flag bit is MF_ERROR, which is cleared when the menu structure is created and set if adding or changing a menu entry causes a memory error. All menu flags are described in the enum MenuFlagsEnum.

See also: MenuBegin, MenuKey


MenuGetTopRedef

short MenuGetTopRedef (HANDLE ExecHandle, short Item);

Gets the index of a toolbox icon.

MenuGetTopRedef returns the ID of the child item whose icon is used by the top-level parent Item as a redefinition icon which belongs to the menu associated with the handle ExecHandle. See MenuTopRedef for more info.

See also: MenuBegin, MenuTopRedef, MenuTopSelect


MenuItemDef

AMS 2.00 or higher

void *MenuItemDef (HANDLE ExecHandle, short ID, unsigned short *Type);

Returns a pointer to the data of a menu item.

Given a menu item ID, MenuItemDef returns a pointer to the text, ICON, or BITMAP defining it (or NULL if ID was not found in the menu identified by ExecHandle) and returns its type in Type. ExecHandle is a handle returned from MenuBegin.

The value returned in Type can be one of the following types (or 0 if not found), as defined in the enum DynMenuFlags:

DMF_TEXT The pointer returned points to a text string.
DMF_ICON The pointer returned points to an ICON structure.
DMF_BITMAP The pointer returned points to a BITMAP structure.

See also: MenuBegin, DynMenuAdd, DynMenuChange


MenuKey

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

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);
}

See also: MenuBegin


MenuLoad

AMS 2.00 or higher

HANDLE MenuLoad (const void *BaseMenu, unsigned short Size);

Begins a dynamically created menu using a prefilled static menu as the starting point.

MenuLoad creates a dynamic menu, using the prefilled static menu structure BaseMenu with the size Size (in bytes) as the starting point. It copies the menu's items, flags, width, and height from the static structure. MenuLoad returns the handle of the new dynamically created menu which may be used in DynMenuAdd or DynMenuChange and then passed to MenuBegin to draw the menu, or returns H_NULL if there was not enough memory.

Note: Please see MenuPopup for more informations on menu structures, and take a look at the proposed method to execute menus as described in MenuNew.

See also: MenuBegin, MenuNew, DynMenuAdd, DynMenuChange


MenuNew

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

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


MenuOff

AMS 2.00 or higher

void MenuOff (HANDLE ExecHandle);

Disables a toolbar menu.

MenuOff grays-out (i.e. disables) the top-level menu defined by ExecHandle (a handle returned from MenuBegin). To re-enable it, call MenuOn.

See also: MenuBegin, MenuOn


MenuOn

void MenuOn (HANDLE ExecHandle);

Redraws a toolbar menu.

MenuOn redraws the menu associated with the handle ExecHandle, where ExecHandle is a handle returned from the MenuBegin function. This may be useful after executing functions like MenuTopSelect, or after calling MenuOff. Note that items that were disabled with MenuTopStat remain disabled and therefore shaded.

See also: MenuBegin, MenuOff, MenuTopStat


MenuPopup

unsigned short MenuPopup (const void *MenuPtr, short x, short y, unsigned short start_option);

Executes a popup menu given a pointer to a popup menu structure.

MenuPopup works exactly like PopupDo, except instead of the handle, a pointer to the menu structure is given as the parameter. PopupDo internally calls HeapDeref, then passes the returned pointer to this function. This function is mainly used internally in the TIOS. Its advantage in comparison with PopupDo is the fact that the complete popup menu structure may be given as a static pre-filled array of bytes, and you can pass the pointer to such a structure to the MenuPopup function. This will save a lot of memory, because you do not need to call PopupNew and a lot of functions like PopupAddText. Moreover, MenuPopup allows executing menus with more than one level of submenus even in AMS 1.xx, which is not possible otherwise. But note that the menu structure is a quite complicated variable-shape structure, so if you do not know exactly what you are doing, avoid this function! As the menu structure has a variable length and shape, it can not be strictly described as a C language type, but it will be described here using non-formal C-like syntax. Note that toolbar menus use the same structure:

packed struct MENU
  {
    unsigned short DisplayOffset;  // Contains offset to Display[0] from here
    unsigned short Flags;          // Various flags: see text below
    unsigned short TotalItems;     // Total number of items
    unsigned char Width;           // Menu width, 0 for popup menus
    unsigned char Height;          // Menu height
    unsigned short MainItems;      // Number of main items only
    unsigned short DynSize;        // Dynamic size (see text below)
    unsigned short RedefOffset;    // Offset to RedefIcons, 0 if RedefItems = 0
    unsigned short RedefItems;     // Number of redefinable icons
    long separator = -1;

    MENU_ENTRY main_entries [];    // for each main item
    long separator = -1;

    struct
      {
        MENU_ENTRY sub_entries []; // for each submenu item
        long separator = -1;
      } cascade [];                // for each submenu

    packed union
      {
        ICON Icon;          // Used in toolbars with icons instead of text
        char Text [];       // Text, zero terminated
      } Display [];         // for each menu item

    struct
      {
        unsigned short ID;  // ID number
        ICON Icon;          // Corresponding icon description
      } RedefIcons [];      // for each redefinable icon (if any)
  };

The Flags field contains various flags defined in the enum MenuFlagsEnum. The DynSize field for dynamically created menus (i.e. menus created with PopupNew) contains the total length of the MENU structure in bytes (this info is needed for the heap manager). For statically allocated menus, you can put zero in this field. Also, each element of the array Display should be aligned on a word boundary. This is not strictly necessary for text items, but it is necessary for icon items.

Each menu item is described using a variable-length (4 or 6 bytes) structure called MENU_ENTRY, which is described as:

struct MENU_ENTRY
  {
    unsigned short ID;                // Item type (see below) ORed with
                                      //   ID number for this item
    unsigned short Offset;            // Offset of icon/text (from Display[0])
                                      //   or XR_string, depending of item type
    packed union                      // If the item is cascaded (i.e if it has
      {                               //   a submenu), we have an extra offset
        unsigned short CascadeOffset; // Offset from the begining of menu
      } extras;                       //   structure to the begining of the
  };                                  //   description of the cascaded submenu

Possible item types are MT_TEXT (0x8000), MT_XREF (0x9000), and MT_ICON (0xA000). They may optionally be ORed with MT_CASCADE (0x4000) to signalize that the item is cascaded (i.e. that the item has a submenu). All these constants are defined in the enum ItemTypes. The CascadeOffset field exists only if ID & MT_CASCADE is non-zero (i.e. if bit b14 in ID is set). If the Offset field for an item of icon type is not defined, this is an item with redefinable icons (for example, the toolbar menu item in the Geometry application uses such menu items).

Note that the topmost (b15) bit of the ID field is always set, and the topmost bit of the Offset field is always 0. This is necessary because MENU_ENTRY is a variable length structure (4 or 6 bytes), depending on whether a cascade is defined. To correctly move up and down through menu items, the TIOS uses the following strategy: on pressing down, if MT_CASCADE is set, move down 6 bytes, otherwise move down 4 bytes. On pressing up, move back 4 bytes, then check bit b15. If it is 0, this is an Offset field, so move back another 2 bytes.

All of this will become clearer with a concrete example. A variable-sized variable-shape structure like MENU cannot be defined using standard C initializers, but it may be defined with the help of the built-in assembler. This example (called "Static Popup") defines exactly the same menu as the example given with PopupDo, but saves about 200 bytes:

// Display a predefined popup menu

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

#define MIN_AMS 100           // Compile for AMS 1.00 or higher

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

extern void menu;
asm ("menu:\n"
"        .word  title_text - menu\n"
"        .word  0xD5\n"
"        .word  9\n"
"        .byte  0, 40\n"
"        .word  5\n"
"        .word  0\n"
"        .word  0\n"
"        .word  0\n"
"        .long  -1\n"
"      main_entries:\n"
"        .word  MT_TEXT + 1                   /* | is a comment character, */\n"
"        .word  option_1_text - title_text    /* so use + instead */\n"
"        .word  MT_TEXT + 2\n"
"        .word  option_2_text - title_text\n"
"        .word  MT_TEXT + MT_CASCADE + 3\n"
"        .word  submenu_3_text - title_text\n"
"        .word  submenu_3_cascade - menu\n"
"        .word  MT_TEXT + MT_CASCADE + 4\n"
"        .word  submenu_4_text - title_text\n"
"        .word  submenu_4_cascade - menu\n"
"        .word  MT_TEXT + 5\n"
"        .word  option_5_text - title_text\n"
"        .long  -1\n"
"      submenu_3_cascade:\n"
"        .word  MT_TEXT + 6\n"
"        .word  suboption_3_1_text - title_text\n"
"        .word  MT_TEXT + 7\n"
"        .word  suboption_3_2_text - title_text\n"
"        .word  MT_TEXT + 8\n"
"        .word  suboption_3_3_text - title_text\n"
"        .long  -1\n"
"      submenu_4_cascade:\n"
"        .word  MT_TEXT + 9\n"
"        .word  suboption_4_1_text - title_text\n"
"        .long  -1\n"
"      title_text:\n"
"        .asciz \"EXAMPLE\"\n"
"      option_1_text:\n"
"        .asciz \"Option 1\"\n"
"      option_2_text:\n"
"        .asciz \"Option 2\"\n"
"      submenu_3_text:\n"
"        .asciz \"Submenu 3\"\n"
"      submenu_4_text:\n"
"        .asciz \"Submenu 4\"\n"
"      option_5_text:\n"
"        .asciz \"Option 5\"\n"
"      suboption_3_1_text:\n"
"        .asciz \"Suboption 3.1\"\n"
"      suboption_3_2_text:\n"
"        .asciz \"Suboption 3.2\"\n"
"      suboption_3_3_text:\n"
"        .asciz \"Suboption 3.3\"\n"
"      suboption_4_1_text:\n"
"        .asciz \"Suboption 4.1\"\n");

void _main(void)
{
  MenuPopup (&menu, CENTER, CENTER, 0);
}

There is an alternative method as well. Note that the field DynSize (the tenth and eleventh byte starting from zero) of the MENU structure contains the total length of the structure for dynamically created menus. So you can make a menu using commands like PopupNew, PopupAddText, etc., and then to use VTI and its debugger to pick up bytes from the menu structure knowing the length of it. After this, you may pass a pointer to the pre-filled sequence of bytes picked from VTI to this function. I used this approach in the following (cryptic) example which is functionally equivalent to the example given above:

static long menu[] = {0x4800D5, 0x90028, 0x500BA, 0, -1, 0x80010008,
  0x80020012, 0xC003001C, 0x30C004, 0X260040, 0X80050030, -1, 0x8006003A,
  0x80070048, 0x80080056, -1, 0X80090064, -1, 0x4558414D, 0x504C4500,
  0x4F707469, 0x6F6E2031, 0x4F4F70, 0x74696F6E, 0x20320053, 0x5375626D,
  0x656E7520, 0x33005375, 0x626D656E, 0x75203400, 0x4F707469, 0x6F6E2035,
  0x535375, 0x626F7074, 0x696F6E20, 0x332E3100, 0x5375626F, 0x7074696F,
  0x6E20332E, 0x32005375, 0x626F7074, 0x696F6E20, 0x332E3300, 0x5375626F,
  0x7074696F, 0x6E20342E, 0x31000000};
MenuPopup (&menu, CENTER, CENTER, 0);

See also: PopupDo


MenuSubStat

void MenuSubStat (HANDLE ExecHandle, short ID, short State);

Changes the state (enabled/disabled) of an item in a pulldown menu.

MenuSubStat is very similar to MenuTopStat, but works with items in associated pulldown menus. MenuSubStat changes status of the item with the given ID (see MenuAddText).

See also: MenuTopStat


MenuTopRedef

void MenuTopRedef (HANDLE ExecHandle, short Item, short ID);

Redefines a toolbox icon.

MenuTopRedef redefines the icon in the toolbox Item (0 = first, 1 = second, etc.), which belongs to the menu associated with the handle ExecHandle, to the icon with index Index, i.e. to the icon associated with the submenu with the given ID. The menu must have been started using MenuBegin with the MBF_REDEF flag set. This is used mainly in the Geometry application which has a toolbar menu with redefinable icons. ExecHandle is a handle returned from the MenuBegin function, not one returned from MenuNew.

Note: Such menus cannot be created using commands like MenuNew, MenuAddIcon, etc. The only way to make a such menu is to create an appropriate pre-filled static menu structure, and to pass a pointer to such a structure to MenuBegin. See MenuPopup for more info about menu structures.

See also: MenuBegin, MenuGetTopRedef, MenuTopSelect


MenuTopSelect

void MenuTopSelect (HANDLE ExecHandle, short Item);

Emphasizes a toolbox.

MenuTopSelect emphasizes (selects) the toolbox Item (0 = first, 1 = second, etc.) which belongs to the menu associated with the handle ExecHandle, by drawing a thick border arround the toolbox. The Geometry application uses this feature. This command also redraws the menu. Call this function with Item = -1 to cancel the selection. ExecHandle is a handle returned from the MenuBegin function, not one returned from MenuNew.

See also: MenuBegin, QMenuTopSelect


MenuTopStat

void MenuTopStat (HANDLE ExecHandle, short Item, short State);

Changes the state (enabled/disabled) of a toolbox.

MenuTopStat changes the state of the toolbox Item (0 = first, 1 = second, etc.) which belongs to the menu associated with the handle ExecHandle. ExecHandle is a handle returned from the MenuBegin function, not one returned from MenuNew. State is a boolean value: if it is TRUE, the toolbox will be enabled; if it is FALSE, the toolbox will be disabled (i.e. it will be dimmed and cannot be selected).

MenuTopStat does not redraw the menu according to the new state; this must be done manually by calling MenuOn.

See also: MenuSubStat


MenuUpdate

void MenuUpdate (void);

Draws the default home screen menu.

MenuUpdate redraws the default home screen menu, which is often useful. More precisely, it redraws the menu registered with the current application (for more info, see the EV_registerMenu function from events.h).


PopupAddText

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

Adds a new text item in a popup menu.

PopupAddText adds the text Text to the popup 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, etc. ID is the identification number which PopupDo will return later if the user selected this menu option, and which may be used as the ParentID parameter in another call. If ID is 0, the TIOS will generate the return value automatically (1 for the first menu option, 2 for the second option, etc.). The legal range for ID is 1 to 4095. If ID is greater than 4095, it will be truncated (ANDed with 0x0FFF). The parameter ParentID has the following meaning:

PopupAddText returns H_NULL in case of an error (i.e. out of memory, ParentID not found, ParentID found but it was not a possible parent, or maximum number of items in a menu exceeded), otherwise it returns Handle. If there is an error adding the new entry, the MF_ERROR bit in the menu structure is set (see MenuPopup for more information on menu structures). You can use MenuFlags to retrieve this flag from the structure.

Although the TIOS menu system allows for menus with more than one level of submenus, it is not possible to create such menus using this command. If you really want more levels of nesting, you can use DynMenuAdd, which supports more levels of nesting, but is only available in AMS 2.00 or later. Alternatively, you can use pre-filled static structures and the MenuPopup function. But note that this is somewhat complicated.

This routine may cause heap compression.

Note: If text is longer than 18 characters, it will be truncated by storing a zero byte into the string after the 18th character. You have to be especially careful because the text parameter is not constant in this case.

See also: DynMenuAdd, DynMenuChange, PopupNew, MenuAddText


PopupBegin

AMS 2.00 or higher

HANDLE PopupBegin (HANDLE Handle, short Flags);

Creates a new popup menu with checkmarks features.

PopuBegin allocates a menu-draw structure for a dynamic popup associated with Handle, so that the popup items can use the enable/disable or check mark features of menus. PopupBegin returns a handle which must be passed to PopupBeginDo, not to PopupDo. The Flags parameter is currently not used and should be set to 0.

TI gives a strict method of using dynamic popups that use PopupBegin:

  1. Create an empty, dynamic popup structure with PopupNew.

  2. Build the menu with DynMenuAdd (or PopupAddText).

  3. Pass the handle returned by PopupNew to PopupBegin.

  4. The handle returned by PopupBegin can now be passed to MenuSubStat to enable/disable individual items or MenuCheck to turn on/off or test the status of checkmarks for individual items.

  5. Pass the handle returned from PopupBegin to PopupBeginDo to actually execute the pop-up.

  6. When done with the menu, call MenuEnd on the handle returned from PopupBegin. This will free that handle and the handle returned from PopupNew.

Do not forget that once you call PopupBegin, you may not unlock the handle returned from PopupNew, or call DynMenuAdd, DynMenuChange, or PopupAddText.

This routine may cause heap compression.

Here is an example of a scrolling popup menu with submenus (called "Dynamic Popup Example"):

// A simple popup menu example

#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 handle = PopupNew ("EXAMPLE", 40);
  PopupAddText (handle, -1, "Option 1", 1);
  PopupAddText (handle, -1, "Option 2", 2);
  PopupAddText (handle, 0, "Submenu 3", 3);
  PopupAddText (handle, 0, "Submenu 4", 4);
  PopupAddText (handle, -1, "Option 5", 5);
  PopupAddText (handle, 3, "Suboption 3.1", 6);
  PopupAddText (handle, 3, "Suboption 3.2", 7);
  PopupAddText (handle, 3, "Suboption 3.3", 8);
  PopupAddText (handle, 4, "Suboption 4.1", 9);
  HANDLE exec_handle = PopupBegin (handle, 0);
  MenuCheck (exec_handle, 2, MC_CHECK);
  MenuCheck (exec_handle, 5, MC_FLIP);
  short result = PopupBeginDo (exec_handle, CENTER, CENTER, 0);
  push_longint (result);
  MenuEnd (exec_handle);
}

See also: PopupNew, PopupBeginDo, MenuSubStat, MenuCheck, MenuEnd


PopupBeginDo

AMS 2.00 or higher

short PopupBeginDo (HANDLE ExecHandle, short x, short y, short StartID);

Executes a dynamically allocated popup using a menu-draw handle.

PopupBeginDo draws the popup menu associated with the handle ExecHandle on the screen. ExecHandle must be returned from PopupBegin and not directly from PopupNew; take care never to mix handles.

The top-left corner of the dialog will be the at the position (x, y); the coordinates are absolute screen coordinates. x, y, or both may also have a special value CENTER, which tells PopupBeginDo to center the menu in this dimension. After the execution, the original contents of the screen will be restored. PopupBeginDo returns the identification number (ID) of the selected menu item (see DynMenuAdd), or 0 if the user pressed ESC. StartID determines which option will be selected first when the menu is executed. It seems that StartID works correctly only for menus without submenus. Anyway, you can always pass 0 to StartID. It causes the function to select the first item.

This routine may cause heap compression.

Here is an example of a scrolling popup menu with submenus (called "Dynamic Popup Example"):

// A simple popup menu example

#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 handle = PopupNew ("EXAMPLE", 40);
  PopupAddText (handle, -1, "Option 1", 1);
  PopupAddText (handle, -1, "Option 2", 2);
  PopupAddText (handle, 0, "Submenu 3", 3);
  PopupAddText (handle, 0, "Submenu 4", 4);
  PopupAddText (handle, -1, "Option 5", 5);
  PopupAddText (handle, 3, "Suboption 3.1", 6);
  PopupAddText (handle, 3, "Suboption 3.2", 7);
  PopupAddText (handle, 3, "Suboption 3.3", 8);
  PopupAddText (handle, 4, "Suboption 4.1", 9);
  HANDLE exec_handle = PopupBegin (handle, 0);
  MenuCheck (exec_handle, 2, MC_CHECK);
  MenuCheck (exec_handle, 5, MC_FLIP);
  short result = PopupBeginDo (exec_handle, CENTER, CENTER, 0);
  push_longint (result);
  MenuEnd (exec_handle);
}

See also: PopupBegin, MenuEnd, PopupDo


PopupClear

HANDLE PopupClear (HANDLE Handle);

Clears a popup or toolbar menu structure.

PopupClear erases all menu items from the popup menu associated with the handle Handle, without freeing the memory (the popup structure itself remains intact, only menu items are erased). PopupClear returns H_NULL in case of an error, otherwise it returns Handle.

Note: This function is very useful in menus which are parts of dialogs, if some changes in a dialog box may force menu items to be refilled (for example when the user selects a new folder in the "Open Variable" dialog). Since the dialog box code keeps the handle of the menu, a new one cannot be created. So the old popup menu is cleared and new entries are added to it.

It seems that this function can also be used for toolbar menus. As popups and toolbar menus just differ in some points, it should work just fine. Then Handle is a handle returned from the MenuNew function (not one returned from MenuBegin). Take care not to execute MenuBegin or functions which use the menu in any way just after this function without refilling the menu with new items using MenuAddText or MenuAddIcon, or this will result in a crash. Remember that using this function erases all the items; using a menu with no items inside is nonsense.

Also note that the memory allocated to the handle is not released until the next call to DynMenuAdd or PopupAddText.

See also: PopupNew, DynMenuAdd, DynMenuChange


PopupDo

short PopupDo (HANDLE Handle, short x, short y, short StartID);

Executes a popup menu.

PopupDo draws the popup menu associated with the handle Handle on the screen. Handle must be returned from PopupNew and not from PopupBegin; take care never to mix handles.

The top-left corner of the dialog will be the at the position (xy); the coordinates are absolute screen coordinates. x, y, or both may also have a special value CENTER, which tells PopupDo to center the menu in this dimension. After the execution, the original contents of the screen will be restored. PopupDo returns the identification number (ID) of the selected menu item (see PopupAddText), or 0 if the user pressed ESC. StartID determines which option will be selected first when the menu is executed. It seems that StartID works correctly only for menus without submenus. Anyway, you can always pass 0 to StartID. It causes the function to select the first item.

This routine may cause heap compression.

Here is an example of a scrolling popup menu with submenus (called "Popup Menu Example"):

// A simple popup menu example

#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 101           // Compile for AMS 1.01 or higher

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

// Main Function
void _main(void)
{
  HANDLE handle = PopupNew ("EXAMPLE", 40);
  PopupAddText (handle, -1, "Option 1", 1);
  PopupAddText (handle, -1, "Option 2", 2);
  PopupAddText (handle, 0, "Submenu 3", 3);
  PopupAddText (handle, 0, "Submenu 4", 4);
  PopupAddText (handle, -1, "Option 5", 5);
  PopupAddText (handle, 3, "Suboption 3.1", 6);
  PopupAddText (handle, 3, "Suboption 3.2", 7);
  PopupAddText (handle, 3, "Suboption 3.3", 8);
  PopupAddText (handle, 4, "Suboption 4.1", 9);
  short result = PopupDo (handle, CENTER, CENTER, 0);
  push_longint (result);
  HeapFree (handle);
}

See also: PopupNew, MenuPopup


PopupNew

HANDLE PopupNew (const char *Title, short Height);

Creates a new popup menu.

PopupNew allocates memory for a new popup menu, 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. Title is the title of the menu (you can pass NULL if you do not want a title), and Height is the height of the menu box in pixels (you can pass 0 for autocalculating the height). If the cumulated height of the items in the menu is greater than the available height of the menu box, the contents of the menu will scroll up or down if necessary.

This empty popup structure can be modified with PopupAddText (or DynMenuAdd and DynMenuChange if you wish to use program only on AMS 2.00 or later). The popup can then be executed with PopupDo (or PopupBegin and PopupBeginDo on AMS 2.00 or later if specific menu features are needed).

Note: If Title is longer than 18 characters, it will be truncated by storing a zero byte into the string after the 18th character. You have to be especially careful because the Title parameter is not constant in this case.

See also: PopupDo, PopupBegin, PopupClear, DynMenuAdd, DynMenuChange, PopupAddText


PopupText

const char *PopupText (HANDLE Handle, short ID);

Returns a pointer to the text of a popup menu item.

PopupText returns a pointer to the text of the popup menu item with the identification number ID (see PopupAddText). Handle is the handle associated with the menu. This function does not work with toolbar menus; you must use MenuItemDef, which does the same for toolbar menus on AMS 2.00 or later.

See also: PopupNew, PopupDo, PopupAddText


QMenuTopSelect

AMS 2.00 or higher

unsigned short QMenuTopSelect (HANDLE ExecHandle);

Returns the currently selected top-level menu item.

QMenuTopSelect returns the currently selected top-level menu item (0 = first, 1 = second, etc.) or -1 if none is selected. ExecHandle refers to a menu-draw handle returned from MenuBegin. MenuTopSelect is normally used with redefinable menus.

See also: MenuBegin, MenuTopSelect


VarCreateFolderPopup

HANDLE VarCreateFolderPopup (unsigned short *CurIndex, unsigned short Flags);

Creates a popup menu containing a list of all folders.

VarCreateFolderPopup creates a dynamic popup (or pulldown) menu which contains a list of all folders in the VAT folder table, and returns a handle to it (or H_NULL in case of an error).

The parameter Flags is usually zero, but it may contain additional flags from the enum VCFPFlags:

VCFP_ALL "All" is included as the first option in the list, like in the "View" dialog of the Var-Link window.
VCFP_SKIP_CURDIR The currently active folder is not included in the list.

This function also stores the index of the currently active folder in the word pointed to by CurIndex.

Note: You need to free the returned handle later by calling HeapFree.

This routine may cause heap compression.


DynMenuFlags

enum DynMenuFlags {DMF_TEXT = 0x0001, DMF_ICON = 0x0002, DMF_BITMAP = 0x0004, DMF_CHILD_SUB = 0x1000, DMF_CHILD = 0x2000, DMF_TOP_SUB = 0x4000, DMF_TOP = 0x8000};

An enumeration for describing possible flags associated to dynamic menu entries.

These constants are used as flags, please see the MenuAddText and MenuAddIcon functions for more information.


ItemTypes

enum ItemTypes {MT_TEXT = 0x8000, MT_XREF = 0x9000, MT_ICON = 0xA000, MT_CASCADE = 0x4000};

An enumeration for describing item types in menus.

As these constants are used mainly in "asm" statements, they are defined using a special method, so they are visible for the built-in assembler (i.e. in "asm" statements). See the example given with the MenuPopup command.


MenuBeginFlags

enum MenuBeginFlags {MBF_WITHICON = 0x01, MBF_REDEF = 0x02, MBF_SYS_ALLOC = 0x04, MBF_MAX_MENU_WIDTH = 0x08, MBF_STRIKEOUT = 0x10, MBF_HMENU = 0x20, MBF_NO_DRAWTOP = 0x40};

An enumeration for describing possible flags passed to MenuBegin.

These constant are used as flags, please see the MenuBegin function for more information.


MenuCheckCmds

enum MenuCheckCmds {MC_CHECK = 0, MC_UNCHECK = 1, MC_STATUS = 2, MC_FLIP = 3};

An enumeration for describing possible commands for the MenuCheck function.

These constants are used as commands, meaning that exactly one of the constants must be specified. Please see the MenuCheck function for more information.


MenuFlagsEnum

enum MenuFlagsEnum {MF_POPUP = 0x0001, MF_TOOLBOX = 0x0002, MF_NONSEQ = 0x0004, MF_ICON_TITLE = 0x0008, MF_TEXT_TITLE = 0x0010, MF_NO_NUMS = 0x0020, MF_NO_UNAMED = 0x0040, MF_DYN_POPUP = 0x0080, MF_ALT_ICONS = 0x0100, MF_BITMAP_TITLE = 0x0200, MF_ERROR = 0x0800, MF_ICONS_OVERLAP = 0x1000, MF_TITLE = 0x0218};

An enumeration for describing possible flags contained in a dynamic menu.

These constant are used as flags, please see the MenuFlags function for more information. Note that MF_TITLE is a combination of MF_TEXT_TITLE, MF_ICON_TITLE, and MF_BITMAP_TITLE.


MenuKeyValues

enum MenuKeyValues {M_NOITEM = 0, M_NOTMENUKEY = -2};

Contains predefined return values of MenuKey.


VCFPFlags

enum VCFPFlags {VCFP_ALL = 0x01, VCFP_SKIP_CURDIR = 0x02};

Describes possible flags for VarCreateFolderPopup.

The constants in this enumeration are used as flags, meaning that you can combine them through bitwise OR.


Return to the main index