PopupClear Function (ROM Call 0x46)

menus.h

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.


Uses: HeapAlloc, memset, strlen, strncpy
Used by: VarOpen


See also: PopupNew, DynMenuAdd, DynMenuChange