 |
PopupAddText |
Function (ROM Call 0x44) |
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:
- Use ParentID = -1 for menu items which have no submenu.
- Use ParentID = 0 for menu items which have an associated submenu.
- If ParentID > 0, this is a submenu item which belongs to the submenu
associated to the menu item whose ID equals ParentID.
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