[Main]
Name=DIALOG
Type=Type
Header Files=dialogs.h
Definition=typedef struct { unsigned short TextOffset; unsigned short NumItems; unsigned char Width, Height; Dialog_Callback_t CallBack; DIALOG_ITEM Fields[]; } DIALOG;
See Also=Dialog, DialogAdd, DIALOG_ITEM, DialogNew, SIZED_DIALOG

[Description]
A scructure for defining dialogs.

[Explanation]
DIALOG is the structure to define a pre-filled dialog box, to be used as the
first argument to the <A HREF="$$LINK(Dialog)">Dialog</A> function. It
enables making a dialog without using <A HREF="$$LINK(DialogNew)">DialogNew</A>,
<A HREF="$$LINK(DialogAddTitle)">DialogAddTitle</A>, and all the other macros
that use <A HREF="$$LINK(DialogAdd)">DialogAdd</A>.
<BR><BR>
There is a constraint in this structure which cannot be described within a C
data type: The last item in the <I>Fields</I> array must be an item of type
<A HREF="$$LINK(DialogTypes)">D_END</A>, and all other fields of this item
must be filled with zero.
<BR><BR>
<I>TextOffset</I> is used to know where the strings that the dialog uses are.
Most dialog fields (of type <A HREF="$$LINK(DIALOG_ITEM)">DIALOG_ITEM</A>)
have a member <I>oText</I>, which is of type
<CODE><A HREF="$$INFOLINK(keywords/unsigned)">unsigned</A> <A HREF="$$INFOLINK(keywords/short)">short</A></CODE>
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.
<BR><BR>
<I>NumItem</I> must be set to the number of items without the terminating
<A HREF="$$LINK(DialogTypes)">D_END</A> item. <I>Width</I>, <I>Height</I> and
<I>Callback</I> are the same as the arguments for
<A HREF="$$LINK(DialogNew)">DialogNew</A>.
<BR><BR>
For most of the <A HREF="$$LINK(DIALOG_ITEM)">DIALOG_ITEM</A> structures, the
structures' members are the same as the arguments used by the corresponding
macro made with <A HREF="$$LINK(DialogAdd)">DialogAdd</A>, just care about
using offsets instead of pointers for strings, and add the flag
<A HREF="$$LINK(DialogFlags)">DF_SKIP</A> to ScrollRegions, Menus, Titles and
text.
<BR><BR>
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.
<BR><BR>
Note that this is not really a static structure, since the value of
<I>Callback</I> 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
<A HREF="$$LINK(SIZED_DIALOG)">SIZED_DIALOG</A> macro, which was created to
avoid this problem.
