[Main]
Name=PopupAddText
Type=Function
Subtype=ROM Call
Header Files=menus.h
Definition=HANDLE PopupAddText (HANDLE Handle, short ParentID, const char *Text, short ID);
See Also=DynMenuAdd, DynMenuChange, PopupNew, MenuAddText

[ROM Call]
Index=$44

[Description]
Adds a new text item in a popup menu.

[Explanation]
PopupAddText adds the text <I>Text</I> to the popup menu associated with the handle
<I>Handle</I>. The text added first will be the first option in the menu, the
text added second will be the second option, etc. <I>ID</I> is the identification number
which <A HREF="$$LINK(PopupDo)">PopupDo</A> will return later if the user selected
this menu option, and which may be used as the <I>ParentID</I> parameter in another call.
If <I>ID</I> 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 <I>ID</I> is 1 to 4095. If <I>ID</I> is greater than 4095, it will
be truncated (ANDed with 0x0FFF).
The parameter <I>ParentID</I> has the following meaning:
<UL>
<LI>Use <I>ParentID</I> = -1 for menu items which have no submenu.</LI>
<LI>Use <I>ParentID</I> = 0 for menu items which have an associated submenu.</LI>
<LI>If <I>ParentID</I> &gt; 0, this is a submenu item which belongs to the submenu
associated to the menu item whose <I>ID</I> equals <I>ParentID</I>.</LI>
</UL>
PopupAddText returns <A HREF="$$LINK(alloc.h/H_NULL)">H_NULL</A> in case of an error
(i.e. out of memory, <I>ParentID</I> not found, <I>ParentID</I> found but it was not a
possible parent, or maximum number of items in a menu exceeded),
otherwise it returns <I>Handle</I>. If there is an error adding the new entry, the
<A HREF="$$LINK(MenuFlagsEnum)">MF_ERROR</A> bit in the menu structure is set (see
<A HREF="$$LINK(MenuPopup)">MenuPopup</A> for more information on menu structures).
You can use <A HREF="$$LINK(MenuFlags)">MenuFlags</A> to retrieve this flag from the
structure.
<BR><BR>
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 <A HREF="$$LINK(DynMenuAdd)">DynMenuAdd</A>,
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
<A HREF="$$LINK(MenuPopup)">MenuPopup</A> function. But note that this is somewhat
complicated.
<BR><BR>
This routine may cause heap compression.
<BR><BR>
<B>Note:</B> If <I>text</I> 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 <I>text</I> parameter is <I>not</I> constant in this case.

[References]
In=VarCreateFolderPopup, bascmd.h/cmd_dialog, bascmd.h/cmd_popup, dialogs.h/VarNew, dialogs.h/VarOpen, dialogs.h/VarSaveAs
Out=DynMenuAdd
