1adime_dialogf(3)              Adime API Reference             adime_dialogf(3)
2
3
4

NAME

6       adime_dialogf
7

SYNOPSIS

9       #include <adime.h>
10
11
12       int  adime_dialogf(const  char *title, int x, y, w, const char *format,
13       ...);
14

DESCRIPTION

16       Displays a dialog letting the user  edit  several  different  kinds  of
17       data.   `title´  specifies  the caption of the dialog while `x´ and `y´
18       specify the top left corner of the dialog. Alternatively, either `x´ or
19       `y´  or both can be set to `ADIME_ALIGN_CENTRE´ or `ADIME_ALIGN_RIGHT´,
20       in which case the dialog will be centred  respectively  right  aligned.
21       `w´ specifies the width of the input field. The total width of the dia‐
22       log depends on this number, and on the length of the strings  given  to
23       the dialog.
24
25       The format string consists of one or more field descriptions, each fol‐
26       lowed be exactly one format specifier. The field description is a  hint
27       text used to help the user know what the field should contain. The for‐
28       mat specifier is a percent sign, followed by an identifier, followed by
29       a  pair  of  square  brackets (possibly with some extra options between
30       (which I will refer to as "format modifier")) and can  be  any  of  the
31       following:
32
33       %bool[]
34
35       A  check box, which can be either on or off. Next argument should be an
36       `int *´, which will be set to 0 for off and 1 for on. Don´t  use  other
37       values!
38
39       %greybool[]
40
41       A  three-state  greyable check box. Next argument should be an `int *´,
42       which will be set to 0 for off, 1 for on, or 2 for greyed.   Don´t  use
43       other values!
44
45       %double[x,y], %float[x,y],
46
47       %int[x,y], %short[x,y], %char[x,y],
48
49       %uint[x,y], %ushort[x,y], %uchar[x,y],
50
51       A  number  in  the  given format (uchar, ushort and uint are unsigned).
52       The number will be clamped to the interval `x´ to `y´, inclusive.   You
53       may  omit  `x´  or  `y´ or both (but keep the comma!) to make it be the
54       minimum respectively maximum for the data type. Next argument should be
55       a pointer to the given data type.
56
57       %pdouble[x,y], %pfloat[x,y],
58
59       %pint[x,y], %pshort[x,y], %pchar[x,y],
60
61       %puint[x,y], %pushort[x,y], %puchar[x,y],
62
63       "Plain"  number formats: With the corresponding formats not prefixed by
64       "p", the user can actually enter any mathematical expression, but these
65       formats  disable  that  feature so he can only enter numbers. Otherwise
66       equal to their non-p-prefixed counterparts.
67
68       %string[bytes]
69
70       A string of length <= `bytes´ (in bytes). Next  argument  should  be  a
71       `char *´ with room for at least the given number of characters.  Remem‐
72       ber that the number of characters that fit in the string will  be  less
73       if  you  use  Unicode.  With  UTF-8,  a character may be as long as six
74       bytes, and with Unicode they are always 2 bytes.
75
76       %filename[len,extension,title]
77
78       A filename of length <= `len´. Next argument should be a `char *´  with
79       room  for at least the given number of bytes (this really is bytes, not
80       characters, and a UTF-8 string can have characters  that  are  6  bytes
81       long,  so you should allocate six times as many bytes as you want char‐
82       acters!). The user will be able to enter the  filename  as  a  text  or
83       click a button to bring up a file selector. `extension´ is a semicolon-
84       separated list of file extensions (ie in the format  "bmp;pcx;tga;foo")
85       which  will  be accepted by the file selector. You may omit `extension´
86       (but keep the commas!), meaning that all file formats will be accepted.
87       `title´  is  the  title  of the file selector dialog. You may also omit
88       `title´ (but keep the commas!), meaning that the description  text  for
89       this field will be used.
90
91       %list[lines,list]
92
93       The  user can select an element in a list of strings. `lines´ specifies
94       the height, in lines, of the list box (this can be omitted to  let  the
95       function calculate the height for you). `list´ is a semicolon-separated
96       list of strings (if one or more strings needs to  contain  a  semicolon
97       (´;´)  or  an end bracket (´]´), the character can be escaped by a per‐
98       cent sign (´%´)). Next argument should be an `int *´, which will be set
99       to the index of the string.
100
101       %vlist[lines]
102
103       The  user can select an element in a list of strings. `lines´ specifies
104       the height, in lines, of the list box (this can be omitted to  let  the
105       function calculate the height for you). Next argument should be an `int
106       *´, which will be set to the index of the selected string, and  then  a
107       `char  **´  which  specifies the strings to choose among, then an `int´
108       which tells how many strings the list contains.
109
110       %datafile[lines,types]
111
112       The user can select an element in an Allegro DATAFILE. You should  pass
113       first  an  `int *´, which will be set to the index of the datafile that
114       was selected, and then a `DATAFILE *´, which should be the datafile  to
115       look  in. `lines´ specifies the height, in lines, of the list box (this
116       can be omitted to let the  function  calculate  the  height  for  you).
117       `types´  is  a  semicolon-separated  list  of  datafile types. You must
118       include all four characters in each type, so it could for example  look
119       like this:
120
121          "%datafile[7,BMP ;RLE ;XCMP; CMP]"
122
123
124       %wlist[lines,title,list]
125
126       %wvlist[lines,title]
127
128       %wdatafile[lines,title,types]
129
130       Like  %list[],  %vlist[] and %datafile, but rather than having the list
131       box in the window, a button will be displayed. When the user clicks the
132       button, a new window with the actual list in (and with the given title)
133       will be opened.
134
135       %nothing[]
136
137       No input data. Will only display the preceding description text as usu‐
138       ally.  This  can  be used if you want a section of the dialog to have a
139       special header.
140
141       %line[]
142
143       No input data. Will only display the  preceding  description  text  (if
144       there  is  any) as usually, and then a horizontal delimitor line.  Like
145       %nothing[], this can be used if you want a section of the dialog to  be
146       delimited from the rest of the dialog.
147
148       %button[text]
149
150       A  button  (with  the  given text on) which calls your custom callback.
151       Next argument should be a function pointer, pointing to a  function  of
152       the type
153
154          int my_callback(DIALOG *d);
155
156       This  will  be called when the user clicks the button. It will be given
157       the dialog object representing the button. Its return value  is  a  bit
158       special: If it is 0, then nothing happens. If it is ADIME_REDRAW (which
159       is defined to be the smallest negative number), then the dialog will be
160       redrawn.  If it is any other positive number, then the dialog will exit
161       with that return value not saving the results of the dialog (the  usual
162       behavior  of a cancel button). If it is any other negative number, then
163       the sign will be removed and the unsigned number returned, and the con‐
164       tents  of  the  dialog will be saved (the usual behavior of the ok but‐
165       ton).
166
167       You are allowed to open a new dialog inside your callback, which may be
168       a less messy and more flexible alternative to %dialogf[].
169
170       %buttonrow[BUTTONS]
171
172       One  or  more buttons in a horizontal row. These are displayed the same
173       way as the OK and Cancel buttons (actually, the OK and  Cancel  buttons
174       are  implemented by appending a %buttonrow[] to the end of the dialog).
175       Next argument should be a function pointer, pointing to a  function  of
176       the type:
177
178          int my_callback(DIALOG *d, int n);
179
180       This  will  be  called with the dialog object for the clicked button as
181       the first argument and the index of this button as  the  second  (i.e.,
182       n=1  for  the  first  button, n=2 for the second and so on). The return
183       value works the same way as for %button[] (see above).
184
185       The modifier (BUTTONS) is itself  a  format  string,  consisting  of  a
186       comma-separated list of buttons. Each button begins with the text which
187       will appear on the button. Then comes an  optional  semicolon-separated
188       list of shortcuts to this button. An example may help to clarify:
189
190          %buttonrow[OK;CTRL+O;ENTER,Cancel;ESC,Help;F1;ALT+H]
191
192       This format will display four buttons: OK, Cancel and Help. The OK but‐
193       ton has the shortcuts CTRL-O and  ENTER.  The  Cancel  button  has  the
194       shortcut  ESC.  The Help button has the shortcuts F1 and ALT-H.  Short‐
195       cuts are specified in uppercase, with the state of shift, ctrl, alt etc
196       preceding  the  key  to press. The key has the same name as the `KEY_*´
197       macro defined by  Allegro  (i.e.,  "ENTER"  for  `KEY_ENTER´,  "3"  for
198       `KEY_3´ and "NUMLOCK" for `KEY_NUMLOCK´). The state consists of zero or
199       more key shift flags separated by plus signs. The names  of  these  are
200       the   same   as   Allegro´s   `KB_*_FLAG´  macros  (i.e.,  "SHIFT"  for
201       `KB_SHIFT_FLAG´ and "CAPSLOCK" for `KB_CAPSLOCK_FLAG´).  If  you  write
202       e.g.  CTRL+O,  it means that CTRL must be held down while pressing O in
203       order to activate the shortcut, while it is optional to hold down other
204       key  modifiers, e.g., SHIFT. If you don´t want the shortcut to be acti‐
205       vated  when  SHIFT  is  down  (for  instance),  then  you   can   write
206       CTRL+-SHIFT+O, i.e., you precede the forbidden key with a minus sign.
207
208       %dialogf[buttontext]
209
210       A  button which opens another adime_dialogf() sub-dialog. Next argument
211       should be the title of the dialog as a `char *´, followed by `x´,  `y´,
212       `edit_w´  as  `int´s  and then `format´ as a `char *´.  These arguments
213       correspond to the arguments given to  `adime_dialogf()´.  Depending  on
214       what  `format´ contains, you then have to add more parameters which the
215       sub-dialog will alter. `buttontext´ is the text which will be displayed
216       on  the button which opens the sub-dialog. An example may help to clar‐
217       ify:
218
219          adime_dialogf("My dialog",
220                        ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
221                        "Open sub-dialog:%dialog[Click me!]",
222                        "My sub-dialog",
223                        ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
224                        "Save in text format:%bool[]",
225                        &text_format);
226
227
228       %vdialogf[buttontext]
229
230       This is like %dialogf[], except that the `...´ arguments are  given  as
231       an  `adime_va_list´  rather  than being expanded into the same argument
232       list. (see also `adime_va_list´)
233
234       %chain[]
235
236       This is like an "inline" version of %vdialogf[]: You  should  pass  two
237       arguments,  first a format string and then an `adime_va_list´. The dia‐
238       log defined by this format string and `adime_va_list´ will be  inserted
239       directly into this dialog. (See exchain.c for an example.)
240
241       Any  special characters mentioned here can be escaped by placing a per‐
242       cent sign (´%´) before it, e.g. if you need  a  literal  ´]´  character
243       somewhere  in the format string. The field description may contain new‐
244       lines.
245
246       Returns 1 if the user selected the OK button, and 2 if he selected  the
247       Cancel  button. The `...´ parameters will be left untouched if the user
248       clicked Cancel but they will change to the new values if he clicked OK.
249       The initial values of the parameters will be taken as default values in
250       the dialog objects.
251
252       The debug library is very useful when you use  this  function:  It  can
253       detect  almost  all  illegal  format strings. If it finds one, it shuts
254       down the program with a traceback and writes a description of the error
255       to the file allegro.log.
256
257       An  example  may  help  to clarify things (see also the programs in the
258       examples directory):
259
260          char name_buffer[1024] = "";
261          int age = 20;
262          int shoe_size = 40;
263          int married = 0;
264          char filename_buffer[1024] = "";
265
266          adime_dialogf("Fill in personal data",
267                        ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
268                        "Name%string[1024]"
269                        "Age (years)%int[0,150]"
270                        "%line"
271                        "Shoe size (Swedish units)%float[10,60]"
272                        "Married%bool[]"
273                        "Favourite text file%filename[1024,txt,Select a text file]",
274                        name_buffer,
275                        &age,
276                        &shoe_size,
277                        &married,
278                        filename_buffer);
279
280

SEE ALSO

282       adime_init(3),    adime_vdialogf(3),    adime_bmp(3),    adime_font(3),
283       adime_va_list(3)
284
285
286
287Adime                            version 2.2.1                adime_dialogf(3)
Impressum