CAT_dialog Function (ROM Call 0x125)

events.h

void CAT_dialog (void);

Starts "CATALOG" dialog "applet".

The "CATALOG" dialog is an event driven "applet". CAT_dialog draws the dialog on the screen, installs its own event handler, then exits (without stopping the caller program). It does not enter into a loop (like normal dialogs do) which ends only on pressing ENTER or ESC. Its event handler restores the previously installed handler after the user presses ENTER or ESC, but if the pressed key was the ENTER key, the selected command from the catalog is send as a CM_STRING message after restoring the user handler (which need to be captured via user event handler). That's why it is not so easy to use CAT_dialog in user programs, but this is also not very hard. Here is an example, which opens the "CATALOG" dialog, and displays in the help screen a message which tells what the user selected from the catalog (called "Catalog"):

// Display the catalog and let the user select something

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 100           // Compile for AMS 1.00 or higher

#include <tigcclib.h>         // Include All Header Files

const char *ptr;
HANDLE handle;

CALLBACK void Handler(EVENT *ev)
{
  if (ev->Type == CM_STRING)
    ptr = ev->extra.pasteText;
  else if (ev->Type == CM_HSTRING)
    handle = ev->extra.hPasteText;
  ER_throw (1);
}

void _main(void)
{
  EVENT ev;
  char buffer[100];
  ptr = NULL;
  handle = H_NULL;
  EV_captureEvents (Handler);
  CAT_dialog ();
  TRY
    EV_eventLoop ();
  ONERR
    EV_captureEvents (NULL);
  ENDTRY
  if (handle != H_NULL)
    ptr = HLock (handle);
  if (ptr != NULL)
  {
    sprintf (buffer, "You selected \"%s\".", ptr);
    ST_helpMsg (buffer);
  }
  else ST_helpMsg ("You pressed ESC.");
  if (handle != H_NULL)
    HeapFree (handle);
  ev.Type = CM_UNFOCUS;               // This is more due to some
  EV_sendEvent (AP_CURRENT, &ev);     // aesthetical reasons
}
Note that it is important that EV_captureEvents must be called before calling CAT_dialog. This example is a good test whether you understand the principles of event handling or not.

Note: If your program uses this function, you have to define SET_FILE_IN_USE_BIT.


Used by: EV_defaultHandler