PopupBegin Function (ROM Call 0x3F5)

AMS 2.00 or higher menus.h

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


Uses: HeapAlloc, HeapLock, memset


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