Must be called before any other functions in Dime. This will set up some
internal stuff. Returns zero on success, nonzero on error.
Shuts down the Dime system. You don't normally need to call this function
since dime_init() will arrange for it to be called automatically when
your program exits or allegro_exit() is called.
int dialogf(char *title, int x, y, w, char *format, ...);
Displays a dialog letting the user edit several different kinds of data.
The title specifies the caption of the dialog while x and y specify the
top left corner of the dialog. Alternatively, either x or y or both can
be set to ALIGN_CENTRE, in which case the dialog will be centred. w
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
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:
Any special characters mentioned here can be escaped by placing a percent
sign ('%') before it, eg if you need a literal ']' character somewhere in
the format string. The field description may contain newlines.
A check box, which can be either on or off. Next argument should be
an `int *', which will be set to `TRUE' for on and `FALSE' for off.
%int[x,y], %short[x,y], %char[x,y],
%uint[x,y], %ushort[x,y], %uchar[x,y],
A number in the given format (uchar, ushort and uint are unsigned).
The number will be clamped to the interval x to y, inclusive. You
may omit x or y 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.
%pint[x,y], %pshort[x,y], %pchar[x,y],
%puint[x,y], %pushort[x,y], %puchar[x,y],
"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.
A string of length <= len. Next argument should be a `char *'
with room for at least the given number of characters. Remember
that the number of bytes you need to allocate may be more than the
number of characters you specify if you use Unicode! With UTF-8, a
character may be as long as six bytes, and with Unicode they are
always 2 bytes.
A filename of length <= `len'. Next argument should be a `char *'
with room for at least the given number of characters. The user
will be able to enter the filename as a text or click a button to
bring up a file selector. `ext' 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 `ext' (but keep the
commas), meaning that all file formats will be accepted. `title' is
the title of the file selector dialog. You may also omit `title'
(but keep the commas), meaning that the description text for this
field will be used.
The user can select an element in a list of strings. `lines'
specifies the height, in lines, of the list box. `list' 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.
The user can select an element in a list of strings. `lines'
specifies the height, in lines, of the list box. 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 `int' which tells how many strings the
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. `name' will be the title of the dialog
box shown. `types' 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:
"%datafile[Select a picture,BMP ;RLE ;XCMP; CMP]"
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.
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.
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.
A button which opens another dialogf() sub-dialog. Next argument
should be the title of the dialog as a `char *', followed by `x',
`y', `w' as `int's and then `format' as a `char *'. These arguments
correspond to the arguments given to `dialogf()'. Depending on what
`format' contains, you then have to add more parameters which the
sub-dialog will alter. `buttontext' is the text which will be
displayed on the button which opens the sub-dialog. An example may
help to clarify:
dialogf("My dialog", ALIGN_CENTRE, ALIGN_CENTRE, 200,
"Open sub-dialog:%dialog[Click me!]",
"My sub-dialog", ALIGN_CENTRE, ALIGN_CENTRE, 200,
"Save in text format:%bool",
This is like %dialogf, except that the `...' arguments are given
as a `va_list' rather than being expanded into the same argument
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.
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
An example may help to clarify things (see also the example program):
char name_buffer = "";
int age = 20;
int shoe_size = 40;
int married = FALSE;
char filename_buffer = "";
int vdialogf(char *title, int x, y, w, char *format, va_list args);
dialogf("Fill in personal data", ALIGN_CENTRE, ALIGN_CENTRE, 200,
"Shoe size (Swedish units)%float[10,60]"
"Favourite text file%filename[256,txt,Select a text file]",
This is the same as `dialogf()', but with a `va_list' instead of
variable number of arguments.
Back to Contents