[Main]
Name=DialogAddTitleEx
Type=Function
Subtype=Macro
Header Files=dialogs.h
Definition=HANDLE DialogAddTitleEx (HANDLE Handle, short flags, const char *title, short left_button, short right_button);
Real Definition=#define DialogAddTitleEx(h,f,t,l,r) DialogAdd(h,f,0,0,D_HEADER,(char*)(t),(short)(l),(short)(r))

[Description]
Adds a title/header bar and up to two buttons into a dialog box. Extended version.

[Explanation]
DialogAddTitleEx adds a title/header bar with the text <I>title</I> and up to
two buttons to the dialog structure associated with the handle <I>Handle</I>.
<BR><BR>
The parameters <I>left_button</I> and <I>right_button</I> determine the type of
the left and right buttons which eventually will appear at the bottom of the
dialog box (by giving <A HREF="$$LINK(Buttons)">BT_NONE</A> as the parameter,
you can skip adding a button). The set of possible buttons is very limited. See
<A HREF="$$LINK(DlgMessage)">DlgMessage</A> for information about possible
types. If you wish to have buttons without having a title bar, then you must
use an owner draw item (see
<A HREF="$$LINK(DialogAddTextEx)">DialogAddTextEx</A> and the explanation on
owner draw items given with <A HREF="$$LINK(DialogNew)">DialogNew</A> for more
information).
<BR><BR>
The parameter <I>flags</I> can be zero or DF_SCREEN_SAVE if you wish the dialog
code to save the area underneath the dialog box when it is started, DB_MEMFULL
is returned if it cannot. Note that if you use this flag, the title item must
be the first one to be created. These flags are defined in the
<A HREF="$$LINK(DialogFlags)">DialogFlags</A> enumeration.
<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>
DialogAddTitleEx 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>
DialogAddTitleEx is in fact a macro created for your convenience. It calls
<A HREF="$$LINK(DialogAdd)">DialogAdd</A> with D_HEADER as the <I>ItemType</I>
parameter. Note that DialogAddTitleEx is the same macro as
<A HREF="$$LINK(DialogAddTitle)">DialogAddTitle</A> except for the parameter
<I>flags</I> which is always set to zero in
<A HREF="$$LINK(DialogAddTitle)">DialogAddTitle</A>. In both functions, zero is
passed to the <I>x</I> and <I>y</I> parameters. (These parameters are ignored
when you use D_HEADER as the <I>ItemType</I>.)

[References]
Out=DialogAdd
