Main Dialog Functions

dime_init
dime_exit
dialogf
vdialogf

int dime_init(void);
Must be called before any other functions in Dime. This will set up some internal stuff. Returns zero on success, nonzero on error.

int dime_exit(void);
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 dialog.

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:

%bool[]
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.
%double[x,y], %float[x,y],
%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.
%pdouble[x,y], %pfloat[x,y],
%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.
%string[len]
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.
%filename[len,extension,title]
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.
%list[lines,list]
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.
%vlist[lines]
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 list contains.
%datafile[lines,types]
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]"
```
%wlist[lines,title,list]
%wvlist[lines,title]
%wdatafile[lines,title,types]
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.
%nothing[]
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.
%line[]
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.
%dialogf[buttontext]
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[]",
                    &text_format);
```
%vdialogf[buttontext]
This is like %dialogf[], except that the `...' arguments are given as a `va_list' rather than being expanded into the same argument list.

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.

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 file allegro.log.

An example may help to clarify things (see also the example program):

      char name_buffer[1024] = "";
      int age = 20;
      int shoe_size = 40;
      int married = FALSE;
      char filename_buffer[1024] = "";

      dialogf("Fill in personal data", ALIGN_CENTRE, ALIGN_CENTRE, 200,
              "Name%string[256]"
              "Age (years)%int[0,150]"
              "%line"
              "Shoe size (Swedish units)%float[10,60]"
              "Married%bool[]"
              "Favourite text file%filename[256,txt,Select a text file]",
              name_buffer,
              &age,
              &shoe_size,
              &married,
              filename_buffer);

int vdialogf(char *title, int x, y, w, char *format, va_list args);
This is the same as `dialogf()', but with a `va_list' instead of variable number of arguments.

Back to Contents

Main Dialog Functions

dime_init dime_exit dialogf vdialogf

dime_init
dime_exit
dialogf
vdialogf