PopupAddText Function (ROM Call 0x44)

menus.h

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.


Uses: DynMenuAdd
Used by: VarCreateFolderPopup, cmd_dialog, cmd_popup, VarNew, VarOpen, VarSaveAs


See also: DynMenuAdd, DynMenuChange, PopupNew, MenuAddText