DialogAddTextEx Function (Macro)

dialogs.h

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


Note: By default, the DF_SKIP flag is set whenever you try to create text or owner draw items so you will not be able to focus on them.

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

DialogAddTextEx is in fact a macro created for your convenience. It calls DialogAdd with D_TEXT as the ItemType parameter. Note that DialogAddTextEx is the same macro as DialogAddText except for the parameter flags which is always set to zero in DialogAddText.


Uses: DialogAdd