[Main]
Name=DialogAddRequestEx
Type=Function
Subtype=Macro
Header Files=dialogs.h
Definition=HANDLE DialogAddRequestEx (HANDLE Handle, short flags, short x, short y, const char *label, unsigned short offset, short MaxLen, short width);
Real Definition=#define DialogAddRequestEx(h,f,x,y,t,o,m,w) DialogAdd(h,f,x,y,D_EDIT_FIELD,(char*)(t),(short)(o),(short)(m),(short)(w))

[Description]
Adds a request/edit box into a dialog box. Extended version.

[Explanation]
DialogAddRequestEx adds a request box (i.e. an input line edit box) to the
dialog structure associated with the handle <I>Handle</I> at the position
(<I>x</I>,<I>y</I>), where the coordinates are relative to the top-left corner
of the dialog box. An optional label <I>label</I> will appear in front of the
request box. An empty string, "", is used to indicate no label.
<BR><BR>
The maximal number of characters which may be entered is determined by the
parameter <I>MaxLen</I> (<I>MaxLen</I> must at most have the size of the
<I>RequestBuffer</I> given to <A HREF="$$LINK(DialogDo)">DialogDo</A>), and
<I>width</I> determines the actual display width of the request box
(<I>MaxLen</I> 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 <I>width</I> characters may fit into the box. So, the
real display width of box in pixels will be <I>width</I>*6, because the widest
character 'M' is 6 pixels wide. If you try to enter a string with more than
<I>width</I> characters, the content of the request box will scroll, and if you
try to have a string longer than <I>MaxLen</I>, the system will prevent you
from doing so. If <I>width</I> is wider than the actually available width of
the dialog box, the request box will be truncated at the edge of the dialog
box.
<BR><BR>
The parameter <I>offset</I> determines what will be the initial content of the
request box, and where the entered characters will be stored. See
<A HREF="$$LINK(DialogDo)">DialogDo</A> for information on how and where the
entered characters are actually stored.
<BR><BR>
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.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="$$LINK(DialogFlags)">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
  <TD>DF_SCROLLABLE</TD>
  <TD>Set this flag if you want this item to be scrollable in a scroll
      region.</TD>
</TR>
<TR>
  <TD>DF_SKIP</TD>
  <TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
  <TD>DF_SCREEN_SAVE</TD>
  <TD>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.</TD>
</TR>
<TR>
  <TD>DF_TAB_ELLIPSES</TD>
  <TD>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.)</TD>
</TR>
<TR>
  <TD>DF_TAB_SPACES</TD>
  <TD>AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any
      dots.</TD>
</TR>
</TABLE>
<BR>
<B>Note:</B> 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 '<B>.</B>' characters up to the length of the longest label, except
if the label finishes with '<B>:</B>': In that case, the label will be padded
with space characters ('<B>:</B>' will also be displayed).
<BR><BR>
DialogAddRequestEx returns <A HREF="$$LINK(alloc.h/H_NULL)">H_NULL</A> in case
of an error, may return <A HREF="$$LINK(DialogMessages)">DB_MEMFULL</A> if you
used <A HREF="$$LINK(DialogFlags)">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddRequestEx is in fact a macro created for your convenience. It calls
<A HREF="$$LINK(DialogAdd)">DialogAdd</A> with D_EDIT_FIELD as the
<I>ItemType</I> parameter. Note that DialogAddRequestEx is the same macro as
<A HREF="$$LINK(DialogAddRequest)">DialogAddRequest</A> except for the parameter
<I>flags</I> which is always set to zero in
<A HREF="$$LINK(DialogAddRequest)">DialogAddRequest</A>.

[References]
Out=DialogAdd
