[Main]
Name=DialogAddTextEx
Type=Function
Subtype=Macro
Header Files=dialogs.h
Definition=HANDLE DialogAddTextEx(HANDLE Handle, short flags, short x, short y, const char *text);
Real Definition=#define DialogAddTextEx(h,f,x,y,t) DialogAdd(h,f,x,y,D_TEXT,(char*)(t))

[Description]
Adds a text, an image, or a custom item into a dialog box.

[Explanation]
DialogAddTextEx gives two possibilities:
<BR><BR>
The first one (if, as is the case of
<A HREF="$$LINK(dialogs.h/DialogAddText)">DialogAddText</A>, the <I>flags</I> parameter
doesn't contain the DF_OWNER_DRAW flag) is to add the text <I>text</I> 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.
<BR><BR>
The second possibility (when the <I>flags</I> parameter contains the
DF_OWNER_DRAW flag) is that DialogAddText can add any kind of item 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. (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 <A HREF="$$LINK(dialogs.h/DialogNew)">DialogNew</A>
for more details on the <I>CallBack</I> function). See the DF_OWNER_DRAW flag
below for more information.
<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(dialogs.h/DialogFlags)">DialogFlags</A> enumeration (DF_OWNER_DRAW
is very important as it can increase the numbers of possible items in dialogs):
<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_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_OWNER_DRAW</TD>
  <TD>AMS 2.00 or higher: The callback function (see
      <A HREF="$$LINK(dialogs.h/DialogNew)">DialogNew</A> for more information) is
      responsible for drawing this item (which can be text, an image, or
      anything else). The parameters <I>text</I>, <I>x</I> and <I>y</I> will in
      this case be ignored. This can only be done if the dialog was created with
      <A HREF="$$LINK(dialogs.h/DialogNew)">DialogNew</A> and not
      <A HREF="$$LINK(dialogs.h/DialogNewSimple)">DialogNewSimple</A>.<BR><BR>
      If the DF_OWNER_DRAW flag is set, then the callback is passed the item
      identification number and a pointer to an
      <A HREF="$$LINK(dialogs.h/OWNER_DRAW_STRUCT)">OWNER_DRAW_STRUCT</A> structure. 
      The first value <I>Item</I> in this structure is a direct pointer to the
      <A HREF="$$LINK(dialogs.h/DIALOG_ITEM)">DIALOG_ITEM</A> structure for the item to
      be drawn. The second value <I>pW</I> is a pointer to the
      <A HREF="$$LINK(wingraph.h/WINDOW)">WINDOW</A> 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).</TD>
</TR>
</TABLE>
<BR><BR>
<B>Note:</B> 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.

<BR><BR>
DialogAddTextEx returns <A HREF="$$LINK(alloc.h/H_NULL)">H_NULL</A> in case
of an error, may return <A HREF="$$LINK(dialogs.h/DialogMessages)">DB_MEMFULL</A> if you
used <A HREF="$$LINK(dialogs.h/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>
DialogAddTextEx is in fact a macro created for your convenience. It calls
<A HREF="$$LINK(dialogs.h/DialogAdd)">DialogAdd</A> with D_TEXT as the <I>ItemType</I>
parameter. Note that DialogAddTextEx is the same macro as
<A HREF="$$LINK(dialogs.h/DialogAddText)">DialogAddText</A> except for the parameter
<I>flags</I> which is always set to zero in
<A HREF="$$LINK(dialogs.h/DialogAddText)">DialogAddText</A>.

[References]
Out=dialogs.h/DialogAdd
