DialogAdd Function (ROM Call 0x33)

dialogs.h

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

The parameter flags depends on the type of element you are creating and can be a combination of the following flags, defined in the DialogFlags enum:

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.

Note: If you want your program to work in AMS 1.xx, you cannot pass D_MENU, D_DYNPOPUP, and D_XFLAGS to this function. Nevertheless, you can initialize a DIALOG structure with these items, and the program will still work on AMS 1.xx.


Uses: HeapRealloc, HeapSize, memcpy, memmove, memset, strlen
Used by: DialogAddPulldown, DialogAddRequest, DialogAddText, DialogAddTitle, DialogAddDynamicPulldown, DialogAddDynamicRequest, DialogAddMenu, DialogAddPulldownEx, DialogAddRequestEx, DialogAddScrollRegion, DialogAddStaticPulldown, DialogAddTextEx, DialogAddTitleEx, DialogAddXFlags, DlgMessage, VarNew, VarOpen, VarSaveAs, cmd_dialog, cmd_request, EV_defaultHandler, HomeExecute, VarSaveTitle


See also: DialogDo, DialogNew, DIALOG