DIALOG Type

dialogs.h

typedef struct {
unsigned short TextOffset;
unsigned short NumItems;
unsigned char Width, Height;
Dialog_Callback_t CallBack;
DIALOG_ITEM Fields[];
} DIALOG;

A scructure for defining dialogs.

DIALOG is the structure to define a pre-filled dialog box, to be used as the first argument to the Dialog function. It enables making a dialog without using DialogNew, DialogAddTitle, and all the other macros that use DialogAdd.

There is a constraint in this structure which cannot be described within a C data type: The last item in the Fields array must be an item of type D_END, and all other fields of this item must be filled with zero.

TextOffset is used to know where the strings that the dialog uses are. Most dialog fields (of type DIALOG_ITEM) have a member oText, which is of type unsigned short as well. For each item, both numbers will be added to the address of the DIALOG structure, and the result must be the address of the string. Offsets are shorts and therefore they cannot be greater than 65535, so having a DIALOG structure on the stack with strings on the heap or vice versa certainly will not work. Even if both the dialog structure and the strings are on the stack, you must be sure that the addresses of all strings are greater than the address of the DIALOG structure; for example because both the DIALOG structure and the strings are contained in a larger structure.

NumItem must be set to the number of items without the terminating D_END item. Width, Height and Callback are the same as the arguments for DialogNew.

For most of the DIALOG_ITEM structures, the structures' members are the same as the arguments used by the corresponding macro made with DialogAdd, just care about using offsets instead of pointers for strings, and add the flag DF_SKIP to ScrollRegions, Menus, Titles and text.

The order in wich you place the items is very important. Usually, the order should be the same as the visual order of the items, because it defines the order in which you move between items with the arrow keys. It also defines each item's identification number, which is passed to the callback function.

Note that this is not really a static structure, since the value of Callback depends on where the program is placed in memory, and the handles or pointers to each pulldown can vary at each execution. If you store this structure as a static structure or in a data file, think about changing the values of pointers and handles each time you execute your program. (The pointer to the callback can be relocated at load time by AMS though.) Also, DIALOG contains a variable-size array of items, and variable-size arrays cannot be initialized with non-constant values. However, a DIALOG instance is usually non-constant. See the SIZED_DIALOG macro, which was created to avoid this problem.


See also: Dialog, DialogAdd, DIALOG_ITEM, DialogNew, SIZED_DIALOG