<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Adime - API Reference: Main Dialog Functions
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Main Dialog Functions">Main Dialog Functions</a></h1>
<ul>
<li><a href="#ADIME_DATE">ADIME_DATE</a>
<li><a href="#adime_dialogf">adime_dialogf</a>
<li><a href="#adime_exit">adime_exit</a>
<li><a href="#adime_init">adime_init</a>
<li><a href="#adime_lowlevel_dialogf">adime_lowlevel_dialogf</a>
<li><a href="#adime_lowlevel_vdialogf">adime_lowlevel_vdialogf</a>
<li><a href="#adime_va_arg">adime_va_arg</a>
<li><a href="#adime_va_end">adime_va_end</a>
<li><a href="#adime_va_list">adime_va_list</a>
<li><a href="#adime_va_start">adime_va_start</a>
<li><a href="#adime_vdialogf">adime_vdialogf</a>
<li><a href="#ADIME_VERSION_MAJOR">ADIME_VERSION_MAJOR</a>
<li><a href="#ADIME_VERSION_MINOR">ADIME_VERSION_MINOR</a>
<li><a href="#ADIME_VERSION_PATCH">ADIME_VERSION_PATCH</a>
</ul>
<p><br>
<hr><font size="+1"><b>int <a name="adime_init">adime_init</a>(void);</b></font><br>
Initializes the Adime system. Call it before using any other Adime
functions and after calling `allegro_init()'. Returns zero on success and
nonzero on error.
<blockquote><font size="-1" face="helvetica,verdana"><em><b>See also:</b></em>
<a href="#adime_exit">adime_exit</a>.</font></blockquote>
<hr><font size="+1"><b>int <a name="adime_exit">adime_exit</a>(void);</b></font><br>
Shuts down the Adime system. You don't normally need to call this function
since `adime_init()' will arrange for it to be called automatically when
your program exits or `allegro_exit()' is called.
<blockquote><font size="-1" face="helvetica,verdana"><em><b>See also:</b></em>
<a href="#adime_init">adime_init</a>.</font></blockquote>
<hr><font size="+1"><b>#define <a name="ADIME_VERSION_MAJOR">ADIME_VERSION_MAJOR</a></b></font><br>
<font size="+1"><b>#define <a name="ADIME_VERSION_MINOR">ADIME_VERSION_MINOR</a></b></font><br>
<font size="+1"><b>#define <a name="ADIME_VERSION_PATCH">ADIME_VERSION_PATCH</a></b></font><br>
<font size="+1"><b>#define <a name="ADIME_DATE">ADIME_DATE</a></b></font><br>
The version number (major.minor.patch) of your version of Adime, and the
date when it was released in the form yyyymmdd.
<p><br>
<hr><font size="+1"><b>int <a name="adime_dialogf">adime_dialogf</a>(const char *title, int x, y, w, const char *format, ...);</b></font><br>
Displays a dialog letting the user edit several different kinds of data.
<tt>`title'</tt> specifies the caption of the dialog while <tt>`x'</tt> and <tt>`y'</tt> specify the
top left corner of the dialog. Alternatively, either <tt>`x'</tt> or <tt>`y'</tt> or both
can be set to <tt>`ADIME_ALIGN_CENTRE'</tt> or <tt>`ADIME_ALIGN_RIGHT'</tt>, in which case
the dialog will be centred respectively right aligned. <tt>`w'</tt> specifies the
width of the input field. The total width of the dialog depends on this
number, and on the length of the strings given to the dialog.
<p>
The format string consists of one or more field descriptions, each
followed be exactly one format specifier. The field description is a hint
text used to help the user know what the field should contain. The format
specifier is a percent sign, followed by an identifier, followed by a
pair of square brackets (possibly with some extra options between (which
I will refer to as "format modifier")) and can be any of the following:
<ul><li>
%bool[]<br>
A check box, which can be either on or off. Next argument should be
an `int *', which will be set to 0 for off and 1 for on. Don't use
other values!
<li>
%greybool[]<br>
A three-state greyable check box. Next argument should be an
`int *', which will be set to 0 for off, 1 for on, or 2 for greyed.
Don't use other values!
<li>
%double[x,y], %float[x,y],<br>
%int[x,y], %short[x,y], %char[x,y],<br>
%uint[x,y], %ushort[x,y], %uchar[x,y],<br>
A number in the given format (uchar, ushort and uint are unsigned).
The number will be clamped to the interval <tt>`x'</tt> to <tt>`y'</tt>, inclusive.
You may omit <tt>`x'</tt> or <tt>`y'</tt> or both (but keep the comma!) to make it be
the minimum respectively maximum for the data type. Next argument
should be a pointer to the given data type.
<li>
%pdouble[x,y], %pfloat[x,y],<br>
%pint[x,y], %pshort[x,y], %pchar[x,y],<br>
%puint[x,y], %pushort[x,y], %puchar[x,y],<br>
"Plain" number formats: With the corresponding formats not prefixed
by "p", the user can actually enter any mathematical expression,
but these formats disable that feature so he can only enter
numbers. Otherwise equal to their non-p-prefixed counterparts.
<li>
%string[bytes]<br>
A string of length <= <tt>`bytes'</tt> (in bytes). Next argument should be
a `char *' with room for at least the given number of characters.
Remember that the number of characters that fit in the string will
be less if you use Unicode. With UTF-8, a character may be as long
as six bytes, and with Unicode they are always 2 bytes.
<li>
%filename[len,extension,title]<br>
A filename of length <= <tt>`len'</tt>. Next argument should be a `char *'
with room for at least the given number of bytes (this really is
bytes, not characters, and a UTF-8 string can have characters that
are 6 bytes long, so you should allocate six times as many bytes as
you want characters!). The user will be able to enter the filename
as a text or click a button to bring up a file selector. <tt>`extension'</tt>
is a semicolon-separated list of file extensions (ie in the format
"bmp;pcx;tga;foo") which will be accepted by the file selector. You
may omit <tt>`extension'</tt> (but keep the commas!), meaning that all file
formats will be accepted. <tt>`title'</tt> is the title of the file selector
dialog. You may also omit <tt>`title'</tt> (but keep the commas!), meaning
that the description text for this field will be used.
<li>
%list[lines,list]<br>
The user can select an element in a list of strings. <tt>`lines'</tt>
specifies the height, in lines, of the list box (this can be
omitted to let the function calculate the height for you). <tt>`list'</tt>
is a semicolon-separated list of strings (if one or more strings
needs to contain a semicolon (';') or an end bracket (']'), the
character can be escaped by a percent sign ('%')). Next argument
should be an `int *', which will be set to the index of the
string.
<li>
%vlist[lines]<br>
The user can select an element in a list of strings. <tt>`lines'</tt>
specifies the height, in lines, of the list box (this can be
omitted to let the function calculate the height for you). Next
argument should be an `int *', which will be set to the index of
the selected string, and then a `char **' which specifies the
strings to choose among, then an <tt>`int'</tt> which tells how many
strings the list contains.
<li>
%datafile[lines,types]<br>
The user can select an element in an Allegro DATAFILE. You should
pass first an `int *', which will be set to the index of the
datafile that was selected, and then a `DATAFILE *', which should
be the datafile to look in. <tt>`lines'</tt> specifies the height, in
lines, of the list box (this can be omitted to let the function
calculate the height for you). <tt>`types'</tt> is a semicolon-separated
list of datafile types. You must include all four characters in
each type, so it could for example look like this:
<pre>
"%datafile[7,BMP ;RLE ;XCMP; CMP]"
</pre>
<li>
%wlist[lines,title,list]<br>
%wvlist[lines,title]<br>
%wdatafile[lines,title,types]<br>
Like %list[], %vlist[] and %datafile, but rather than having the
list box in the window, a button will be displayed. When the user
clicks the button, a new window with the actual list in (and with
the given title) will be opened.
<li>
%nothing[]<br>
No input data. Will only display the preceding description text as
usually. This can be used if you want a section of the dialog to
have a special header.
<li>
%line[]<br>
No input data. Will only display the preceding description text (if
there is any) as usually, and then a horizontal delimitor line.
Like %nothing[], this can be used if you want a section of the
dialog to be delimited from the rest of the dialog.
<li>
%button[text]<br>
A button (with the given text on) which calls your custom callback.
Next argument should be a function pointer, pointing to a function
of the type
<pre>
int my_callback(DIALOG *d);
</pre>
This will be called when the user clicks the button. It will be
given the dialog object representing the button. Its return value is
a bit special: If it is 0, then nothing happens. If it is
ADIME_REDRAW (which is defined to be the smallest negative number),
then the dialog will be redrawn. If it is any other positive number,
then the dialog will exit with that return value not saving the
results of the dialog (the usual behavior of a cancel button). If it
is any other negative number, then the sign will be removed and the
unsigned number returned, and the contents of the dialog will be
saved (the usual behavior of the ok button).
You are allowed to open a new dialog inside your callback, which may
be a less messy and more flexible alternative to %dialogf[].
<li>
%buttonrow[BUTTONS]<br>
One or more buttons in a horizontal row. These are displayed the
same way as the OK and Cancel buttons (actually, the OK and Cancel
buttons are implemented by appending a %buttonrow[] to the end of
the dialog). Next argument should be a function pointer, pointing to
a function of the type:
<pre>
int my_callback(DIALOG *d, int n);
</pre>
This will be called with the dialog object for the clicked button
as the first argument and the index of this button as the second
(i.e., n=1 for the first button, n=2 for the second and so on). The
return value works the same way as for %button[] (see above).
The modifier (BUTTONS) is itself a format string, consisting of a
comma-separated list of buttons. Each button begins with the text
which will appear on the button. Then comes an optional
semicolon-separated list of shortcuts to this button. An example may
help to clarify:
<pre>
%buttonrow[OK;CTRL+O;ENTER,Cancel;ESC,Help;F1;ALT+H]
</pre>
This format will display four buttons: OK, Cancel and Help. The
OK button has the shortcuts CTRL-O and ENTER. The Cancel button has
the shortcut ESC. The Help button has the shortcuts F1 and ALT-H.
Shortcuts are specified in uppercase, with the state of
shift, ctrl, alt etc preceding the key to press. The key has the
same name as the `KEY_*' macro defined by Allegro (i.e., "ENTER" for
<tt>`KEY_ENTER'</tt>, "3" for <tt>`KEY_3'</tt> and "NUMLOCK" for <tt>`KEY_NUMLOCK'</tt>). The
state consists of zero or more key shift flags separated by plus
signs. The names of these are the same as Allegro's `KB_*_FLAG'
macros (i.e., "SHIFT" for <tt>`KB_SHIFT_FLAG'</tt> and "CAPSLOCK" for
<tt>`KB_CAPSLOCK_FLAG'</tt>). If you write e.g. CTRL+O, it means that CTRL
must be held down while pressing O in order to activate the
shortcut, while it is optional to hold down other key modifiers,
e.g., SHIFT. If you don't want the shortcut to be activated when
SHIFT is down (for instance), then you can write CTRL+-SHIFT+O,
i.e., you precede the forbidden key with a minus sign.
<li>
%dialogf[buttontext]<br>
A button which opens another adime_dialogf() sub-dialog. Next
argument should be the title of the dialog as a `char *', followed
by <tt>`x'</tt>, <tt>`y'</tt>, <tt>`edit_w'</tt> as <tt>`int'</tt>s and then <tt>`format'</tt> as a `char *'.
These arguments correspond to the arguments given to
`adime_dialogf()'. Depending on what <tt>`format'</tt> contains, you then have
to add more parameters which the sub-dialog will alter. <tt>`buttontext'</tt>
is the text which will be displayed on the button which opens the
sub-dialog. An example may help to clarify:
<pre>
adime_dialogf("My dialog",
ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
"Open sub-dialog:%dialog[Click me!]",
"My sub-dialog",
ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
"Save in text format:%bool[]",
&text_format);
</pre>
<li>
%vdialogf[buttontext]<br>
This is like %dialogf[], except that the `...' arguments are given
as an <tt>`adime_va_list'</tt> rather than being expanded into the same
argument list. (see also <tt>`adime_va_list'</tt>)
<li>
%chain[]<br>
This is like an "inline" version of %vdialogf[]: You should pass two
arguments, first a format string and then an <tt>`adime_va_list'</tt>. The
dialog defined by this format string and <tt>`adime_va_list'</tt> will be
inserted directly into this dialog. (See exchain.c for an example.)
</ul>
Any special characters mentioned here can be escaped by placing a percent
sign ('%') before it, e.g. if you need a literal ']' character somewhere
in the format string. The field description may contain newlines.
<p>
Returns 1 if the user selected the OK button, and 2 if he selected the
Cancel button. The `...' parameters will be left untouched if the user
clicked Cancel but they will change to the new values if he clicked OK.
The initial values of the parameters will be taken as default values in
the dialog objects.
<p>
The debug library is very useful when you use this function: It can
detect almost all illegal format strings. If it finds one, it shuts down
the program with a traceback and writes a description of the error to the
file allegro.log.
<p>
An example may help to clarify things (see also the programs in the
examples directory):
<pre>
char name_buffer[1024] = "";
int age = 20;
int shoe_size = 40;
int married = 0;
char filename_buffer[1024] = "";
adime_dialogf("Fill in personal data",
ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
"Name%string[1024]"
"Age (years)%int[0,150]"
"%line"
"Shoe size (Swedish units)%float[10,60]"
"Married%bool[]"
"Favourite text file%filename[1024,txt,Select a text file]",
name_buffer,
&age,
&shoe_size,
&married,
filename_buffer);
</pre>
<blockquote><font size="-1" face="helvetica,verdana"><em><b>See also:</b></em>
<a href="#adime_init">adime_init</a>,
<a href="#adime_vdialogf">adime_vdialogf</a>,
<a href="adime001.html#Adime Colors">Adime Colors</a>,
<a href="adime001.html#adime_bmp">adime_bmp</a>,
<a href="adime001.html#adime_font">adime_font</a>,
<a href="#adime_va_list">adime_va_list</a>.</font></blockquote>
<hr><font size="+1"><b>int <a name="adime_vdialogf">adime_vdialogf</a>(const char *title, int x, y, w, const char *format,
adime_va_list args);</b></font><br>
This is the same as `adime_dialogf()', but with an <tt>`adime_va_list'</tt> instead
of variable number of arguments.
<blockquote><font size="-1" face="helvetica,verdana"><em><b>See also:</b></em>
<a href="#adime_dialogf">adime_dialogf</a>,
<a href="#adime_va_list">adime_va_list</a>.</font></blockquote>
<hr><font size="+1"><b>int <a name="adime_lowlevel_dialogf">adime_lowlevel_dialogf</a>(const char *title, int x, y, w,
const char *format, ...);</b></font><br>
This is the same as `adime_dialogf()', except it doesn't include the
default <tt>`OK'</tt> and <tt>`Cancel'</tt> buttons. You will normally want to call this
function with the last format being "%buttonrow[]".
<blockquote><font size="-1" face="helvetica,verdana"><em><b>See also:</b></em>
<a href="#adime_dialogf">adime_dialogf</a>.</font></blockquote>
<hr><font size="+1"><b>int <a name="adime_lowlevel_vdialogf">adime_lowlevel_vdialogf</a>(const char *title, int x, y, w,
const char *format, adime_va_list args);</b></font><br>
This is the same as `adime_lowlevel_dialogf()', but with an
<tt>`adime_va_list'</tt> instead of variable number of arguments.
<blockquote><font size="-1" face="helvetica,verdana"><em><b>See also:</b></em>
<a href="#adime_dialogf">adime_dialogf</a>,
<a href="#adime_va_list">adime_va_list</a>.</font></blockquote>
<hr><font size="+1"><b>typedef <a name="adime_va_list">adime_va_list</a>;</b></font><br>
<font size="+1"><b>void <a name="adime_va_start">adime_va_start</a>(adime_va_list ap, first_arg);</b></font><br>
<font size="+1"><b>TYPE <a name="adime_va_arg">adime_va_arg</a>(adime_va_list ap, TYPE);</b></font><br>
<font size="+1"><b>void <a name="adime_va_end">adime_va_end</a>(adime_va_list ap);</b></font><br>
Because of weirdnesses in the C language, some things that Adime does with
va_lists would not be portable if it used a va_list directly. Instead you
always have to use this replacement API, which works exactly like the
standard API for va_lists, but is more portable. Also, if you pass an
<tt>`adime_va_list'</tt> to another function, which reads an argument with
`adime_va_arg()', then the <tt>`adime_va_list'</tt> will have advanced to the same
position in the calling function as in the called function. In particular,
after calling `adime_vdialogf()', the <tt>`adime_va_list'</tt> will have advanced
to after the last argument used by Adime.
<p>
The following example shows how `adime_dialogf()' is implemented in terms
of `adime_vdialogf()':
<pre>
int adime_dialogf(char *title, int x, int y, int edit_w,
char *format, ...)
{
int ret;
va_list ap;
va_start(ap, format);
ret = adime_vdialogf(title, x, y, edit_w, format, ap);
va_end(ap);
return ret;
}
</pre>
See documentation for the standard <tt>`va_list'</tt>, `va_start()', `va_arg()' and
`va_end()' for more information.
<blockquote><font size="-1" face="helvetica,verdana"><em><b>See also:</b></em>
<a href="#adime_vdialogf">adime_vdialogf</a>,
<a href="#adime_dialogf">adime_dialogf</a>,
<a href="#adime_lowlevel_vdialogf">adime_lowlevel_vdialogf</a>.</font></blockquote>
<hr><a href="adime.html">Back to Contents</a>
</body>
</html>
