adime_dialogf

adime_dialogf(3)              Adime API Reference             adime_dialogf(3)



NAME
       adime_dialogf

SYNOPSIS
       #include <adime.h>


       int adime_dialogf(const char *title, int x, y, w, const char *format,
       ...);

DESCRIPTION
       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:

       %bool[]

       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!

       %greybool[]

       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!

       %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[bytes]

       A string of length <= `bytes´ (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.

       %filename[len,extension,title]

       A filename of length <= `len´. 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. `extension´ 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 `extension´
       (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 (this can be omitted to let the
       function calculate the height for you). `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 (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 `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. `lines´ specifies the height, in lines, of the list box (this
       can be omitted to let the function calculate the height for you).
       `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[7,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.

       %button[text]

       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

          int my_callback(DIALOG *d);

       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[].

       %buttonrow[BUTTONS]

       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:

          int my_callback(DIALOG *d, int n);

       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:

          %buttonrow[OK;CTRL+O;ENTER,Cancel;ESC,Help;F1;ALT+H]

       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 `KEY_ENTER´, "3"
       for `KEY_3´ and "NUMLOCK" for `KEY_NUMLOCK´). 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
       `KB_SHIFT_FLAG´ and "CAPSLOCK" for `KB_CAPSLOCK_FLAG´). 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.

       %dialogf[buttontext]

       A button which opens another adime_dialogf() sub-dialog. Next argument
       should be the title of the dialog as a `char *´, followed by `x´, `y´,
       `edit_w´ as `int´s and then `format´ as a `char *´.  These arguments
       correspond to the arguments given to `adime_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:

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


       %vdialogf[buttontext]

       This is like %dialogf[], except that the `...´ arguments are given as
       an `adime_va_list´ rather than being expanded into the same argument
       list. (see also `adime_va_list´)

       %chain[]

       This is like an "inline" version of %vdialogf[]: You should pass two
       arguments, first a format string and then an `adime_va_list´. The
       dialog defined by this format string and `adime_va_list´ will be
       inserted directly into this dialog. (See exchain.c for an example.)

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


SEE ALSO
       adime_init(3), adime_vdialogf(3), adime_bmp(3), adime_font(3),
       adime_va_list(3)



Adime                            version 2.2.1                adime_dialogf(3)