DialogAddRequestEx Function (Macro)

dialogs.h

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.

Note: On AMS 1.xx, all request boxes in one dialog box will be aligned according to the request box which has the longest label, except when the label string finishes with a '`' character (code 96). In such case, the request box will start immediately after the label string ('`' is a special character, which will not be displayed). When the label doesn't end with '`', it can be padded with '.' characters up to the length of the longest label, except if the label finishes with ':': In that case, the label will be padded with space characters (':' will also be displayed).

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

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


Uses: DialogAdd