Main Dialog Functions

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:

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