Routines for creating dialogs
Note: If your program uses functions from this header file, you probably have to
define SET_FILE_IN_USE_BIT.
| short Dialog (DIALOG *DialogPtr, short x, short y, char *RequestBuffer, short *PopupBuffer); |
Shows and activates a dialog box given a pointer to a dialog structure.
Dialog works exactly like DialogDo, except instead of the
handle, a pointer to the dialog structure is given as the parameter.
DialogDo internally calls HeapDeref,
then passes the returned pointer to the Dialog function. This function is mainly used
internally in TIOS. Its advantage compared to DialogDo is
the fact that the complete dialog structure may be given as a static pre-filled
array of bytes, and you can give a pointer to such a structure to the Dialog function.
It will save a lot of memory, because you do not need to call DialogNew and
a lot of functions like DialogAddText etc.
If DialogPtr points to a dynamically created dialog box (i.e a dialog created with DialogNew
or DialogAdd), the heap block that stores the dialog box must be locked
because this routine may cause heap compression.
Dialog may return:
KEY_ENTER if the user pressed ENTER to close the dialog box.
KEY_ESC if the user pressed ESC to close the dialog box.
-1 if there is not enough memory to open the menu for the dialog box.
See also: DialogDo
| HANDLE DialogAdd (HANDLE Handle, short flags, short x, short y, short ItemType, ...); |
Adds an item into a dialog box.
DialogAdd is a universal item-adding function. It is a very complicated
function which accepts 6 to 12 parameters depending on the type of the item
which will be added. This type is determined by the ItemType
parameter. In fact, all other functions whose names begin with "DialogAdd..."
(such as DialogAddTextEx,
DialogAddTitleEx,
DialogAddRequestEx,
DialogAddPulldownEx, etc.) are
implemented as macros which call DialogAdd with appropriate parameters (for
easier usage), so you can mainly avoid this function. You can read the
dialogs.h header file to see how exactly these macros are
implemented.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
DialogAdd returns H_NULL in case of an
error, may return DB_MEMFULL if you used
DF_SCREEN_SAVE, else returns Handle.
This routine (as well as all other 'DialogAdd...' routines) may cause heap
compression.
ItemType can be filled with one of the following commands, defined in
the DialogTypes enum:
| ItemType | Appearance | Additional Parameters | Macro |
| D_HEADER | Title bar, up to two buttons | const char *title, unsigned short LeftButton, unsigned short RightButton |
DialogAddTitleEx |
| D_TEXT | Text or personalized item | const char *text |
DialogAddTextEx |
| D_EDIT_FIELD | Request (edit) box | const char *label, unsigned short offset, unsigned short MaxLen, unsigned short width |
DialogAddRequestEx |
| D_HEDIT | Request (edit) box | const char *label, unsigned short width |
DialogAddDynamicRequest |
| D_POPUP | Pulldown menu | const char *label, void *Popup, unsigned short buffer |
DialogAddStaticPulldown |
| D_DYNPOPUP | AMS 2.00 or higher: Pulldown menu | const char *label, Dialog_GetHandle_t GetPopup, unsigned short index |
DialogAddDynamicPulldown |
| D_HPOPUP | Pulldown menu | const char *label, HANDLE MenuHandle, unsigned short index |
DialogAddPulldownEx |
| D_MENU | AMS 2.00 or higher: Main menu | void *Menu, unsigned short MaxMenuWidth |
DialogAddMenu |
| D_SCROLL_REGION | Scroll region | unsigned short x1, unsigned short y1, unsigned short FirstItem, unsigned short LastItem, unsigned short NumDspItems, unsigned short TotNumItems, unsigned short ItemHeight |
DialogAddScrollRegion |
| D_XFLAGS | AMS 2.00 or higher: Extended dialog properties | unsigned short xFlags1, unsigned short xFlags2, unsigned short xFlags3, unsigned short xFlags4 |
DialogAddXFlags |
| Flag | Item Type | Description |
| DF_SCREEN_SAVE | (any) | When applied to the first item in the dialog, the dialog code saves the area underneath the dialog box when it is started. DialogAdd returns DB_MEMFULL if there is not enough memory to do this. |
| DF_SKIP | (any) | This item is skipped when browsing through items with the arrow keys. For example, all text items should have this flag set. |
| DF_SCROLLABLE | (any) | Set this flag if you want this item to be scrollable in a scroll region. |
| DF_TAB_ELLIPSES | Request box, pulldown menu | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx. |
| DF_TAB_SPACES | Request box, pulldown menu | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots. |
| DF_OWNER_DRAW | Text | AMS 2.00 or higher: The callback function (see DialogNew for more information) is responsible for drawing this item (which can be text, an image, or anything else). This can only be done if the dialog was created with DialogNew and not DialogNewSimple. |
| DF_POPUP_RADIO | Pulldown menu | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu. |
| DF_MAX_MENU_WIDTH | Main menu | AMS 2.00 or higher: Passes MBF_MAX_MENU_WIDTH to MenuBegin when the menu is drawn. |
| DF_CLR_ON_REDRAW | Scroll region | Clears the entire visible scroll region when redrawn. If you do not set this flag, the scroll region will not be cleared before being redrawn, and you might still see the previously drawn items underneath the new ones. |
See also: DialogDo, DialogNew, DIALOG
| HANDLE DialogAddDynamicPulldown (HANDLE Handle, short flags, short x, short y, const char *label, Dialog_GetHandle_t GetPopup, unsigned short index); |
Adds a dynamic pulldown menu into a dialog box.
DialogAddDynamicPulldown adds a pulldown item to the dialog box associated
with the handle Handle at the position (x,y), where the
coordinates are relative to the top-left corner of the dialog box.
When the pulldown is opened, the function passed to the GetPopup
parameter is called (with the identification number of the newly created item
as the value of the ID parameter), and it must return the handle of the
actual popup menu (usually created using
PopupNew). See
menus.h for more information about creating
popups.
An optional label label will appear in front of the request box; an
empty string is used to indicate that no label should be drawn. The parameter
index determines where the result value of executing the pulldown menu
will be stored, and also indicates what the initially selected option will be.
See DialogDo for information on how and where
the result values are actually stored.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration:
| DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region. |
| DF_SKIP | This item is skipped when browsing through items with the arrow keys. |
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx. |
| DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots. |
| DF_POPUP_RADIO | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu. |
| HANDLE DialogAddDynamicRequest (HANDLE Handle, short flags, short x, short y, const char *label, unsigned short width); |
Adds a request/edit box with a dynamic buffer into a dialog box.
DialogAddDynamicRequest adds a request box (i.e. an input line edit box) with a
dynamic buffer to the dialog structure associated with the handle Handle
at the position (x,y), where the coordinates are relative to the
top-left corner of the dialog box. An optional label label will appear
in front of the request box. An empty string, "", is used to indicate no label.
Items created with DialogAddDynamicRequest doesn't use the
RequestBuffer array passed to the Dialog
function, so they do not need the offset and MaxLen values like
normal edit items as described in
DialogAddRequestEx. Instead, the
callback function (see DialogNew for more
information) is called with the first parameter equal to DB_GET_EDIT_HANDLE and
the second parameter equal to the item's identification number. The callback
should then return the handle of an edit buffer of at least width bytes
long. width determines the actual width of the request box (This is very
useful when you need to prevent the user from overstepping a special size such
as file names). It will be such that the widest string made of width
characters may fit into the box. So, the real width of box in pixels will be
width*6, because the widest character 'M' is 6 pixels wide. If you try
to enter a string with more than width characters, the system will
prevent you from doing so. If width is wider than the actually available
width of the dialog box, the request box will be truncated at the edge of the
dialog box.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration:
| DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region. |
| DF_SKIP | This item is skipped when browsing through items with the arrow keys. |
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. (It is the default on AMS 1.xx. See the note below for more information.) |
| DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots. |
| HANDLE DialogAddMenu (HANDLE Handle, short flags, short x, short y, void *Menu, unsigned short MaxMenuWidth); |
Adds a menu into a dialog box.
DialogAddMenu adds the menu Menu, with a maximum width of
MaxMenuWidth (or zero to automatically calculate the width) at the
position (x,y) to the dialog structure associated with the handle
Handle, where the coordinates are relative to the top-left corner of the
dialog box.
A menu item is defined by a pointer Menu to a toolbar menu structure
created statically (i.e. you must include a pre-filled static menu in your
source code) or dynamically with MenuNew
(in this case the caller must ensure the structure remains locked while in use
in the dialog box, i.e. use HLock in the
same way as for MenuBegin). The menu
is drawn by an internal call to
MenuBegin. When a menu key is pressed,
the callback's (see DialogNew for more
information) Message value will be the item's identification number and
Value will be passed the menu handle returned from
MenuBegin in the high word and the key
code in the low word. You can specify a maximum width for your menu in
MaxMenuWidth or zero if you want it to be automatically calculated. Each
dialog box can have at most one menu. The creation of menus is explained in the
header file menus.h. Note that if you want a
menu, you must write a callback function, else you will not be able to do
anything but dispaying it!
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration:
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_MAX_MENU_WIDTH | AMS 2.00 or higher: Passes MBF_MAX_MENU_WIDTH to MenuBegin when the menu is drawn. |
| HANDLE DialogAddPulldown (HANDLE Handle, short x, short y, const char *prompt, HANDLE MenuHandle, unsigned short index); |
Adds a pulldown/popup menu into a dialog box.
DialogAddPulldown works exactly as DialogAddPulldownEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_HPOPUP passed as a command and zero passed as the flags. All the parameters are explained in DialogAddPulldownEx.
| HANDLE DialogAddPulldownEx (HANDLE Handle, short flags, short x, short y, const char *label, HANDLE PopupMenu, unsigned short index); |
Adds a pulldown/popup menu into a dialog box. Extended version.
DialogAddPulldownEx adds the pulldown menu PopupMenu to the dialog
structure associated with the handle Handle at the position
(x,y), where the coordinates are relative to the top-left corner
of the dialog box.
label is the label which will appear in front of the popup menu (or ""
if you don't want any name), and MenuHandle is the handle of the
associated menu which needs to be created using the
PopupNew function (the same functions
are used for creating pulldown and popup menus). See
menus.h for more info about creating popups.
The text must fit into one line of the dialog box.
The parameter index determines where the result value of executing the
pulldown menu will be stored, and also indicates what the initially selected
option will be. See DialogDo for information on
how and where the result values are actually stored.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration:
| DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region. |
| DF_SKIP | This item is skipped when browsing through items with the arrow keys. |
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx. |
| DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots. |
| DF_POPUP_RADIO | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu. |
| HANDLE DialogAddRequest (HANDLE Handle, short x, short y, const char *prompt, unsigned short offset, short MaxLen, short width); |
Adds a request/edit box into a dialog box.
DialogAddRequest works exactly as DialogAddRequestEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_EDIT_FIELD passed as a command and zero passed as the flags. All the parameters are explained in DialogAddRequestEx.
| HANDLE DialogAddRequestEx (HANDLE Handle, short flags, short x, short y, const char *label, unsigned short offset, short MaxLen, short width); |
Adds a request/edit box into a dialog box. Extended version.
DialogAddRequestEx adds a request box (i.e. an input line edit box) to the
dialog structure associated with the handle Handle at the position
(x,y), where the coordinates are relative to the top-left corner
of the dialog box. An optional label label will appear in front of the
request box. An empty string, "", is used to indicate no label.
The maximal number of characters which may be entered is determined by the
parameter MaxLen (MaxLen must at most have the size of the
RequestBuffer given to DialogDo), and
width determines the actual display width of the request box
(MaxLen can be very usefull when you need to prevent the user from
overstepping a special size such as file names). It will be such that the
widest string made of width characters may fit into the box. So, the
real display width of box in pixels will be width*6, because the widest
character 'M' is 6 pixels wide. If you try to enter a string with more than
width characters, the content of the request box will scroll, and if you
try to have a string longer than MaxLen, the system will prevent you
from doing so. If width is wider than the actually available width of
the dialog box, the request box will be truncated at the edge of the dialog
box.
The parameter offset determines what will be the initial content of the
request box, and where the entered characters will be stored. See
DialogDo for information on how and where the
entered characters are actually stored.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration:
| DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region. |
| DF_SKIP | This item is skipped when browsing through items with the arrow keys. |
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. (It is the default on AMS 1.xx. See the note below for more information.) |
| DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots. |
| HANDLE DialogAddScrollRegion (HANDLE Handle, short flags, short x, short y, unsigned short x1, unsigned short y1, unsigned short FirstItem, unsigned short LastItem, unsigned short NumDspItems, unsigned short TotNumItems, unsigned short ItemHeight); |
Adds a rectangular item-scrolling region to a dialog box.
DialogAddScrollRegion adds a rectangular item-scrolling region to the dialog
structure associated with the handle Handle from the
(x, y) position to the (x1, y1) position, where
all coordinates are relative to the top-left corner of the dialog box.
A scroll region defines a group of items that will scroll as the user moves
through the items. The identification number of the first scrollable should
be set in FirstItem and the last scrollable item in LastItem.
NumDspItems defines the number of items that are displayed at one time.
The total number of scrollable item should be set in TotNumItems and
the height of each item in ItemHeight. Every scrollable item must be
defined contiguously and have the DF_SCROLLABLE flag set and must not be of
MENU, HEADER or XFLAGS type. The coordinates of the scrollable items are
relative to the dialog box except that they may extend beyond the bottom
coordinate of the dialog box. They are defined assuming a virtual scroll
region.
It's very easy to cause display bugs using this function (of course, that
won't crash your calculator, but the dialog can easily become ugly), so here
is a method you can use to avoid those bugs: First, the standard item height
is the height of the biggest item (often the EDIT item which is 10 pixel high),
so the minimum value in ItemHeight should be 10 in most cases. Then, to
avoid any display bugs, the y axis should be the y value of your first
displayed item - 2 and y1 axis should be the y value of your last
displayed item + 8. I.e. if you wish to scroll 8 items and only display items
3 by 3 (but please use the available screen space: don't just restrict the
items displayed at a time to 3 just because everyone else does it), and the
first scrollable item is item number 4 (the last displayed item at the
beginning is therefore item 6), the calculation should be:
y=(item 4 y axis)-2 and y1=(item 6 y axis)+8). The difference
x1-x should also be greater than the width of the largest item
(else it will result in display bugs). I don't really understand the utility
of such a TotNumItems parameter as it should always be equal to
LastItem-FirstItem+1. The flag DF_CLR_ON_REDRAW is very useful
and should be set in most cases (see below).
Note: If you use a SCROLL_REGION, it must be the first item defined in
the dialog box. A dialog box can therefore have at most one scroll region.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration:
| DF_SKIP | This item is skipped when browsing through items with the arrow keys. |
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_CLR_ON_REDRAW | Clears the entire visible scroll region when redrawn. If you do not set this flag, the scroll region will not be cleared before being redrawn, and you might still see the previously drawn items underneath the new ones. |
| HANDLE DialogAddStaticPulldown (HANDLE Handle, short flags, short x, short y, const char *label, void *Popup, unsigned short index); |
Adds a static pulldown/popup menu into a dialog box.
DialogAddStaticPulldown uses the pointer Popup to a static pre-filled
popup menu structure (popup menus and dialog pulldowns are in fact the same
structure) and adds this pulldown menu to the dialog structure associated with
the handle Handle at the position (x,y), where the
coordinates are relative to the top-left corner of the dialog box.
label is the label which will appear in front of the popup menu (or ""
if you don't want any name), and Popup is a prefilled static
popup structure (i.e. you must write
this popup in your source code; for dynamic pop-ups use
DialogAddPulldownEx) of the
associated menu. See menus.h for more info about
creating static popups. The text must fit into one line of the dialog box.
The parameter index determines where the result value of executing the
pulldown menu will be stored, and also indicates what the initially selected
option will be. See DialogDo for information on
how and where the result values are actually stored.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
DialogAddStaticPulldown works like
DialogAddPulldownEx, but only accepts
a static pre-filled dialog Popup instead of a handle.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration:
| DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region. |
| DF_SKIP | This item is skipped when browsing through items with the arrow keys. |
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx. |
| DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots. |
| DF_POPUP_RADIO | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu. |
| HANDLE DialogAddText (HANDLE Handle, short x, short y, const char *text); |
Adds a text into a dialog box.
DialogAddText works exactly as DialogAddTextEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_TEXT passed as a command and zero passed as the flags. All the parameters are explained in DialogAddTextEx.
| HANDLE DialogAddTextEx(HANDLE Handle, short flags, short x, short y, const char *text); |
Adds a text, an image, or a custom item into a dialog box.
DialogAddTextEx gives two possibilities:
The first one (if, as is the case of
DialogAddText, the flags parameter
doesn't contain the DF_OWNER_DRAW flag) is to add the text text to the
dialog structure associated with the handle Handle at the position
(x, y), where the coordinates are relative to the top-left corner
of the dialog box.
The second possibility (when the flags parameter contains the
DF_OWNER_DRAW flag) is that DialogAddText can add any kind of item to the
dialog structure associated with the handle Handle at the position
(x, y), where the coordinates are relative to the top-left corner
of the dialog box. (This position can later be ignored so owner draw items will
not necessarily have to stick to this position.) You can create every kind of
item you wish with this function (such as text, buttons, bitmaps...) as far as
you create a callback function (see DialogNew
for more details on the CallBack function). See the DF_OWNER_DRAW flag
below for more information.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter flags can be a combination of the following, defined in
the DialogFlags enumeration (DF_OWNER_DRAW
is very important as it can increase the numbers of possible items in dialogs):
| DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region. |
| DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box. |
| DF_OWNER_DRAW | AMS 2.00 or higher: The callback function (see
DialogNew for more information) is
responsible for drawing this item (which can be text, an image, or
anything else). The parameters text, x and y will in
this case be ignored. This can only be done if the dialog was created with
DialogNew and not
DialogNewSimple. If the DF_OWNER_DRAW flag is set, then the callback is passed the item identification number and a pointer to an OWNER_DRAW_STRUCT structure. The first value Item in this structure is a direct pointer to the DIALOG_ITEM structure for the item to be drawn. The second value pW is a pointer to the WINDOW structure for the dialog box. Using this pointer, the callback can draw anything and anywhere to the dialog box (all clipped to the dialog box window). |
| HANDLE DialogAddTitle (HANDLE Handle, const char *title, short left_button, short right_button); |
Adds a title bar and up to two buttons into a dialog box.
DialogAddTitle works exactly as DialogAddTitleEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_HEADER passed as a command and zero passed as the flags. All the parameters are explained in DialogAddTitleEx.
| HANDLE DialogAddTitleEx (HANDLE Handle, short flags, const char *title, short left_button, short right_button); |
Adds a title/header bar and up to two buttons into a dialog box. Extended version.
DialogAddTitleEx adds a title/header bar with the text title and up to
two buttons to the dialog structure associated with the handle Handle.
The parameters left_button and right_button determine the type of
the left and right buttons which eventually will appear at the bottom of the
dialog box (by giving BT_NONE as the parameter,
you can skip adding a button). The set of possible buttons is very limited. See
DlgMessage for information about possible
types. If you wish to have buttons without having a title bar, then you must
use an owner draw item (see
DialogAddTextEx and the explanation on
owner draw items given with DialogNew for more
information).
The parameter flags can be zero or DF_SCREEN_SAVE if you wish the dialog
code to save the area underneath the dialog box when it is started, DB_MEMFULL
is returned if it cannot. Note that if you use this flag, the title item must
be the first one to be created. These flags are defined in the
DialogFlags enumeration.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
DialogAddTitleEx returns H_NULL in case
of an error, may return DB_MEMFULL if you
used DF_SCREEN_SAVE, else returns
Handle. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
DialogAddTitleEx is in fact a macro created for your convenience. It calls
DialogAdd with D_HEADER as the ItemType
parameter. Note that DialogAddTitleEx is the same macro as
DialogAddTitle except for the parameter
flags which is always set to zero in
DialogAddTitle. In both functions, zero is
passed to the x and y parameters. (These parameters are ignored
when you use D_HEADER as the ItemType.)
| HANDLE DialogAddXFlags (HANDLE Handle, short flags, unsigned short xFlags1, unsigned short xFlags2, unsigned short xFlags3, unsigned short xFlags4); |
Adds extended dialog properties into a dialog box.
DialogAddXFlags adds extended dialog properties to the dialog structure
associated with the handle Handle.
The XFLAGS item defines an array of four extended unsigned short flags (i.e.
xFlags1, xFlags2, xFlags3, xFlags4.) Currently only
xFlags1 is used: the three remaining values should always be set to zero
for future compatibility.
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
The parameter xFlags1 may contain a combination of the following flags,
defined in the DialogXFlags enumeration:
| XF_ALLOW_VARLINK | Setting this extended xflag allows all EDIT (=request) items in the dialog box to allow the [VAR-LINK] key to be activated within the dialog box and to paste results to the edit item. If this xflag or XF_VARLINK_SELECT_ONLY is not set, then when [VAR-LINK] is pressed in a dialog box, the dialog will be closed and VAR-LINK will be activated. |
| XF_NO_ALPHA_LOCK | On the TI-89, Alpha-Lock is turned on for all dialog boxes with edit items. Setting this extended xflag disables this feature. |
| XF_VARLINK_SELECT_ONLY | This xflag is similar to XF_ALLOW_VARLINK except thet the user may not make any variable changes inside VAR-LINK (like deleting, copying, renaming, or locking variables). |
| XF_TE_REPAINT | This xflag is unknown for the moment. Do not use. |
| 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 (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);
}
| HANDLE DialogNew (short Width, short Height, Dialog_Callback_t Callback); |
Creates a new dialog box which can interact with the user program.
DialogNew acts like DialogNewSimple,
but accepts a pointer to a user callback function Callback as a third
parameter (i.e. you must pass the pointer of a function you wrote in your
source code which contains the parameter types defined by
Dialog_Callback_t). This function is
called more than once during the dialog's execution.
Such a user function allows for interaction between the dialog box and the
user program, and permits the creation of dialog boxes which dynamically
change their contents during execution. This is a kind of event-driven
programming: When an event occurs in the dialog, the Callback function
will be called with a specific Message parameter Message that should
be processed so as to know what data the parameter Value contains.
Events are only sent on a few occasions, which include:
when an item in the dialog box is created or recreated;
when an item receives the focus;
when the user acts on an item. The moment the callback function is called depends on the kind of item (some elements need to call the Callback function when they are activated, some others need to call this function when they return from activation). For example, the callback is called after the user pressed ENTER in a request box or after execution of any pulldown menu.
This function has to return a value, whose meaning also depends on the input
Message parameter. However, in simple dialog boxes without any dynamic
elements, you may always pass TRUE, which
is the same as DB_CONTINUE, i.e.
the standard return value. Note that if you do not want to take care of the
Callback function at all (i.e. if you do not want to write such a
function) you can use the already written
NoCallBack function, which does nothing but
return TRUE whatever the entering message
is (but in that case, the best thing is to use
DialogNewSimple, which in fact is a
macro using both DialogNew and NoCallBack).
Note that if you choose not to create a CallBack function, some of the items
(such as D_MENU) and the
DF_OWNER_DRAW flag will not be very
useful for you as they need to be handled in the callback function.
The following table shows what the Message value can be, when events
occur and what you should return from Callback. The constants are
defined in the enum DialogMessages:
| A nonnegative value | This occurs when the user pressed ENTER to activate an item, or to
return from an activated item.
This nonnegative value is in fact the identification number of an item in a dialog. This identification number is created automatically when you use one of the creation functions DialogAdd, DialogAddText, DialogAddPulldown, and all other functions starting with "DialogAdd". A value of 0 represents the first item you created in the dialog box, 1 is the second one, 2 the third one, and so on. The meaning of the Value parameter depends on the type of the item. See below for a list of possible meanings. The return value should be a message from the enum DialogMessages:
|
||||||||
| DB_QACTIVE | Query the status of an item (enabled/disabled).
This occurs whenever an item in the dialog box is created, gets the focus, or whenever the dialog box needs to update the state of the item. In this case, the value passed through Value is the identification number of an item in the dialog (0 for the first one, 1 for the second one, and so on). You should return TRUE if the item is enabled and should not be grayed out, or FALSE if the item is disabled and must be grayed out). Note that static items such as D_TITLE and D_TEXT are not even drawn if they are disabled. |
||||||||
| DB_GET_TITLE | Query the title of a dynamic header.
This event occurs when a special title bar which may be added to the dialog using DialogAdd with ItemType set to D_DYNHEADER is created. The Value parameter will be zero, and the callback function must return the text for the title of the dialog box. Note: as statically created dynamic titles are not known very well for the moment, in most cases you do not have to care about this value. |
||||||||
| DB_GET_EDIT_HANDLE | Query the text buffer of a dynamic edit field.
This event occurs when a special request box which may be added to the dialog using DialogAdd with ItemType set to D_HEDIT (or using DialogAddDynamicRequest) is created or gets the focus. The value contained in Value is the identification number of this edit box item in the dialog. The callback function must return a handle which points to a buffer from where this request box will get its initial value, and where the contents of the request box will be stored. You may need the HeapAlloc function to get a new handle and HeapDeref to access the associated buffer (see the example below). Note: See DialogAddDynamicRequest for more details about this special feature. |
| Pulldown | If the item identified by Message is a pulldown menu (i.e. if this item has been created using DialogAddPulldown or DialogAddPulldownEx, or DialogAdd with ItemType set to D_POPUP, D_HPOPUP or D_DYNPOPUP), the value contained in Value is the identification number of the item selected in the pulldown menu (not one of a dialog item). The event occurs only when the user selects an item and presses ENTER. |
| Request | If the item identified by Message is a request item (i.e. if this item has been created using DialogAddRequest or DialogAddRequestEx, or DialogAdd with ItemType set to D_HEDIT or D_EDIT_FIELD), the value contained in Value is a pointer pointing to the data the user just entered. |
| Menu | If the item identified by Message is a menu (i.e. if this item
has been added using DialogAddMenu
or DialogAdd with ItemType set
to D_MENU), the value contained
in Value is in fact the composition of two values: the 16 most
significant bits (the high word) of Value contain the execution
handle of the menu (the dialog box code calls
MenuBegin initially to get a
handle for the menu) and the 16 least significant bits (the low word)
contain the key pressed by the user to activate the menu (for your
convenience, common key values are defined in the
CommonKeys enum). The macros
LO_WORD and
HI_WORD have been created to get both
values easily. The callback function may activate the menu or change
anything in it if needed. See
MenuKey for more details on
activating a menu.
Note: The return value of a menu differs from that of any other element: Returning a positive value will select (focus on) the dialog item whose identification number is equal to the value you returned. (This feature is mainly used in the TIOS 'MODE' dialog where pressing F1, F2 or F3 changes the page displayed, which is achieved by changing the focus.) With AMS 2.xx the return value can also be one of DB_REDRAW, DB_REDRAW_AND_CONTINUE or DB_EXIT, but not DB_CONTINUE, since that value is positive. |
| Owner Draw Text | If the item identified by Message is an owner draw text/image (i.e. if this item has been created using DialogAdd with ItemType set to D_TEXT and Flags containing DF_OWNER_DRAW), the value contained in Value is a pointer to an OWNER_DRAW_STRUCT structure. The Item field in this structure is a direct pointer to the DIALOG_ITEM structure for the item to be drawn (this is not normally used). The pW field is a pointer to the WINDOW structure for the dialog box. Using this pointer, the callback function can draw anything anywhere to the dialog box (clipped to the window of the dialog box). For example, you can draw simple text using the WinStrXY function, or draw a standard button using DrawStaticButton, or a bitmap using WinBitmapPut, etc. In general, you will be able to use any of the functions from wingraph.h. |
See also: DialogDo, Dialog, DialogAdd, DIALOG
| HANDLE DialogNewSimple (short width, short height); |
Creates a new dialog box.
DialogNewSimple allocates memory for a dialog box with dimensions width x height,
initializes allocated block with necessary structures and returns a handle to it (or H_NULL in case of
error). This routine may cause heap compression.
DialogNewSimple in fact calls DialogNew with
NoCallBack as third parameter.
Note: You can later free the memory by calling HeapFree.
| short DlgMessage (const char *title, const char *message, short left_button, short right_button); |
Displays a message dialog box.
DlgMessage displays a message dialog box, where title is the title string
(pass NULL for no title), and
message is the content of the message. Both title and message
must fit into one screen line, else the calculator will crash (however, on AMS 2.xx, a long
message will simply be wrapped in the dialog box). Parameters left_button
and right_button determine the type of the left and right buttons which will appear
at the bottom of the dialog box. The set of possible buttons is very limited, and possible
types are defined in enum Buttons (any other values will cause a crash).
The meanings of these constants are:
| BT_NONE | No button at all |
| BT_OK | Button "Enter=OK" |
| BT_SAVE | Button "Enter=SAVE" |
| BT_YES | Button "Enter=YES" |
| BT_CANCEL | Button "Esc=CANCEL" |
| BT_NO | Button "ESC=NO" |
| BT_GOTO | Button "Enter=GOTO" |
| short HI_WORD(long); |
Returns the high word from a long value.
This function returns the highest short value (the 16 most significant bits) of a long value. This macro function was created for DialogNew.
| short LO_WORD (long); |
Returns the low word from a long value.
This function returns the lowest short value (the 16 least significant bits) of a long value. This macro function was created for DialogNew.
| short NoCallBack (short Message, long Value); |
Dummy callback function doing nothing.
NoCallBack is a dummy function which does nothing, and always returns 1 as result.
The purpose of this function lies in the fact that it may be given as a third parameter
to the function DialogNew, when there is no need for an
interaction with the user program during the execution of the dialog (i.e. no
"calling back"). DialogNewSimple does exactly this:
it calls DialogNew with NoCallBack as a third parameter.
Note: This routine was in TIOS jump table up to AMS 1.xx. In AMS 2.xx it is not
in the jump table! Here, NoCallBack is implemented on such whay that it can be used on
any version of AMS.
| HSym VarNew (const ESQ *FileTypes, ...); |
Displays the standard "New" dialog.
VarNew implements the standard "New" dialog. The user may select a type to
create as well as the folder to create the new variable in, and then may type
in a variable name.
FileTypes is a pointer to a zero-terminated array of types that are
supported (see VarOpen for more info). VarNew
returns the HSym descriptor of the newly
created symbol, or H_NULL if the user
presses 'ESC' or in case of an error.
This function may cause heap compression.
| HSym VarOpen (const ESQ *FileTypes, ...); |
Displays the standard "Open" dialog.
VarOpen implements the standard "Open" dialog. The user may select a type,
the folder to look in, and finally a symbol in the selected folder which
matches the selected type.
FileTypes is a pointer to a zero-terminated array of types that are
supported. These types are, in fact, tags (see the
Tags enum for more info). Supported
tags are:
EQ_TAG (expression),
STR_TAG (string),
LIST_TAG (list),
MATRIX_TAG (matrix),
PRGM_ITAG (program),
FUNC_ITAG (function),
DATA_TAG (data),
GDB_TAG (Graph Database),
PIC_TAG (picture),
TEXT_TAG (text),
FIG_TAG (geometry figure),
MAC_TAG (geometry macro),
ASM_TAG (assembly program), and
OTH_TAG (custom-type file).
Each value in the FileTypes list will be presented to the user in a
pulldown menu, unless there is only one value in the list (then it will be a
static field).
VarOpen returns the HSym
descriptor of the selected symbol, or
HS_NULL if the user pressed 'ESC' or in
case of an error.
If the FileTypes list contains
OTH_TAG items, an extra parameter of type
char ** is required. This parameter is an array of strings (more
precisely, of char pointers). There must be exactly one char pointer for each
OTH_TAG item in the FileTypes
list, and these pointers should point to the text to display in the pulldown
menu for these custom types.
This function may cause heap compression.
| HSym VarSaveAs (const ESQ *FileTypes, const char *TitleSym, ...); |
Displays the standard "Save Copy As" dialog.
VarSaveAs implements the standard "Save Copy As" dialog. The user may select
a type as well as the folder to save the symbol in, and finally has to enter
the symbol name.
FileTypes is a pointer to a zero-terminated array of types that are
supported (see VarOpen for more info).
TitleSym is a string that will be placed in the title of the dialog
box (the title will have the form "SAVE COPY OF TitleSym AS").
Alternatively, TitleSym may be NULL
if no such title is wanted.
VarSaveAs returns the HSym descriptor of the
newly created symbol, or H_NULL if the
user pressed 'ESC' or in case of an error. This function is essentially the
same as VarNew, only the different dialog type
is used.
This function may cause heap compression.
| #define CENTER (-1) |
A constant to describe a centered position for dialogs.
When used in the DialogDo or PopupDo command as a parameter, CENTER means "center the dialog or popup menu on the screen in x, y or both directions," depending on which parameter CENTER is used as.
enum DialogMessages {
|
An enumeration to describe messages used by a Dialog's Callback.
| enum Buttons {BT_NONE = 0, BT_OK = 1, BT_SAVE = 2, BT_YES = 3, BT_CANCEL = 4, BT_NO = 5, BT_GOTO = 6}; |
An enumeration to describe possible button types.
Describes the button types used in DlgMessage.
| typedef CALLBACK short (*Dialog_Callback_t) (short Message, long Value); |
Callback function type for dialogs.
Dialog_Callback_t is used in DialogNew and in the DIALOG structure to provide a callback mechanism for events in the dialog box.
Deprecated alias: DialogNew_t
| typedef CALLBACK HANDLE (*Dialog_GetHandle_t) (short ID); |
Callback function type returning a handle for a dialog item.
Dialog_GetHandle_t is used in DialogAddDynamicPulldown to let the program generate the menu handle on demand.
typedef struct {
|
A scructure for defining dialog items.
This is the structure that defines an item in a
DIALOG structure.
Note: To declare an Item of type D_END, which is all zeros, you can write:
DIALOG_ITEM empty={.f={}};
Deprecated alias: DIALOG_ITEMS
See also: DIALOG, DialogAdd, SIZED_DIALOG, DialogTypes
typedef struct {
|
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
| enum DialogFlags {DF_TAB_ELLIPSES = 0x01, DF_MAX_MENU_WIDTH = 0x01, DF_SCROLLABLE = 0x02, DF_CLR_ON_REDRAW = 0x04, DF_TAB_SPACES = 0x04, DF_OWNER_DRAW = 0x08, DF_POPUP_RADIO = 0x20, DF_SCREEN_SAVE = 0x40, DF_SKIP = 0x80}; |
An enumeration to describe possible item flags in a dialog box.
This enumeration describes all the possible item flags in a dialog box. See DialogAdd for more informations.
| enum DialogTypes {D_END = 0, D_MENU = 1, D_EDIT_FIELD = 2, D_SCROLL_REGION = 3, D_OPTION = 4, D_RADIO = 5, D_BUTTON = 6, D_TEXT = 7, D_HEADER = 8, D_POPUP = 10, D_DYNPOPUP = 11, D_HEDIT = 12, D_DYNHEADER = 13, D_HPOPUP = 14, D_XFLAGS = 15}; |
An enumeration to describe possible item types in a dialog box.
This enumeration describes all the possible item types in a dialog box. See DialogAdd for more informations.
See also: DialogAdd, DIALOG_ITEM
enum DialogXFlags {
|
An enumeration to describe possible XFlags in a dialog box.
This enumeration describes all the possible XFlags in a dialog box. See DialogAddXFlags for more informations.
typedef struct {
|
A scructure for defining an owner draw item.
This structure defines an owner draw item. A pointer to this structure is given to the callback function when an owner draw item is (re)created. See DialogNew for more informations.
#define SIZED_DIALOG(NumbItems,StrLen) struct {
|
A macro to help defining dialogs, it is nearly the same as DIALOG.
There are two main dificulties one encouters using the DIALOG structure:
First there is a variable size array, and variable size arrays can't be initialized with non constant value.
Secondly it doesn't include strings, which should better be placed just after the DIALOG in memory.
SIZED_DIALOG avoids both of these problems: It needs two argument : the number of Items NumbItems and the size of the all the strings together StrLen, and defines a struct from this, wich is the same as DIALOG but with some place for the strings: you can define a dilalog using SIZED_DIALOG(NumbItems,StrLen)={/*Dialog definition*/}. It is done in the given examples. If you use that macro, it will fill to the right number of Item, and If you forget to add an item with type D_END after the last used Item, it is automatically done.
Using SIZED_DIALOG also helps to get the offset of the strings. You can initialize it with offsetof(SIZED_DIALOG(ItemsNum,0),String)