 |
DialogDo |
Function (ROM Call 0x32) |
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 (x, y),
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