Main Dialog Functions

int adime_init(void);
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.
See also: adime_exit.

int adime_exit(void);
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.
See also: adime_init.

#define ADIME_DATE
The version number (major.minor.patch) of your version of Adime, and the date when it was released in the form yyyymmdd.

int adime_dialogf(const char *title, int x, y, w, const char *format, ...);
Displays a dialog letting the user edit several different kinds of data. `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 `ADIME_ALIGN_CENTRE' or `ADIME_ALIGN_RIGHT', in which case the dialog will be centred respectively right aligned. `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, e.g. 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 programs in the examples directory):

      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,
                    "Age (years)%int[0,150]"
                    "Shoe size (Swedish units)%float[10,60]"
                    "Favourite text file%filename[1024,txt,Select a text file]",
See also: adime_init, adime_vdialogf, Adime Colors, adime_bmp, adime_font, adime_va_list.

int adime_vdialogf(const char *title, int x, y, w, const char *format, adime_va_list args);
This is the same as `adime_dialogf()', but with an `adime_va_list' instead of variable number of arguments.
See also: adime_dialogf, adime_va_list.

int adime_lowlevel_dialogf(const char *title, int x, y, w, const char *format, ...);
This is the same as `adime_dialogf()', except it doesn't include the default `OK' and `Cancel' buttons. You will normally want to call this function with the last format being "%buttonrow[]".
See also: adime_dialogf.

int adime_lowlevel_vdialogf(const char *title, int x, y, w, const char *format, adime_va_list args);
This is the same as `adime_lowlevel_dialogf()', but with an `adime_va_list' instead of variable number of arguments.
See also: adime_dialogf, adime_va_list.

typedef adime_va_list;
void adime_va_start(adime_va_list ap, first_arg);
TYPE adime_va_arg(adime_va_list ap, TYPE);
void adime_va_end(adime_va_list ap);
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 `adime_va_list' to another function, which reads an argument with `adime_va_arg()', then the `adime_va_list' will have advanced to the same position in the calling function as in the called function. In particular, after calling `adime_vdialogf()', the `adime_va_list' will have advanced to after the last argument used by Adime.

The following example shows how `adime_dialogf()' is implemented in terms of `adime_vdialogf()':

      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);

         return ret;
See documentation for the standard `va_list', `va_start()', `va_arg()' and `va_end()' for more information.
See also: adime_vdialogf, adime_dialogf, adime_lowlevel_vdialogf.

Back to Contents