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. |