DialogDo Function (ROM Call 0x32)

dialogs.h

short DialogDo (HANDLE Handle, short x, short y, char *RequestBuffer, short *PulldownBuffer);

Activates and shows a dialog box.

DialogDo activates and shows on the screen the dialog associated with handle Handle. The top-left corner of the dialog will be at the position (xy), where coordinates are absolute screen coordinates. x, y or both may also have a special value CENTER which means "center the dialog on the screen in x, y or both directions". DialogDo returns KEY_ENTER or KEY_ESC, depending on whether the user exits the dialog by pressing ENTER or ESC key (note that structures pointed to by RequestBuffer and PulldownBuffer will be modified regardless of whether the user exits the dialog by pressing ENTER or ESC). It also may return a negative number in a case of error (e.g. not enough memory to display the dialog box). After the execution is finished, the original content of the screen will be restored. This routine may cause heap compression.

Parameter RequestBuffer is the pointer to the buffer where character entered into request boxes will be stored. This buffer may store more than one string; the characters entered into a request box will be stored starting from address RequestBuffer + offset, where offset is the parameter given with the DialogAddRequest command which created this request box. Each stored string will be zero terminated. This buffer may be pre-filled with the initial content which will appear in request boxes. Namely, initial content of any request box will be a sequence of characters starting from address RequestBuffer + offset up to the first zero ('\0') character (where offset is the parameter given when the request box is created). If the dialog does not contain any request boxes, RequestBuffer may be NULL.

Parameter PulldownBuffer is the pointer to the buffer where return values of execution of pulldown menus will be stored. This buffer is, in fact, an array of integers; the return value of executing a pulldown menu will be stored in PulldownBuffer[index], where index is the parameter given with the DialogAddPulldown command which created this pulldown menu. This array may be pre-filled with the ordinal numbers of initial option in pulldown menus. Namely, initially selected option content of any pulldown menu will be an option with ordinal number PulldownBuffer[index] (where index is the parameter given when the pulldown menu was created). If the dialog does not contain any pulldown menus, PulldownBuffer may be NULL.

Here is a concrete example (called "Dialog Test"), which creates a dialog which asks the user for his name, then displays a message box with a greeting message in which the user's name is included, except if the user pressed the ESC key:

// Display a simple dialog box and let the user enter a name

#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

// Main Function
void _main(void)
{
  char buffer[27] = "Hello ";
    // 6 bytes "Hello ", max. 20 bytes name, 1 zero byte
  HANDLE handle = DialogNewSimple (140, 55);
  DialogAddTitle (handle, "EXAMPLE", BT_OK, BT_CANCEL);
  DialogAddText (handle, 3, 20, "Enter name (max. 20 chars)");
  DialogAddRequest (handle, 3, 30, "Your name", 6, 20, 14);
  if (DialogDo (handle, CENTER, CENTER, buffer, NULL) == KEY_ENTER)
    DlgMessage ("GREETINGS", buffer, BT_OK, BT_NONE);
  HeapFree (handle);
}


Uses: Dialog, HeapLock, HeapUnlock
Used by: DlgMessage, VarNew, VarOpen, VarSaveAs, cmd_dialog, cmd_request, EV_defaultHandler, HomeExecute