1adime_dialogf(3) Adime API Reference adime_dialogf(3)
2
6 adime_dialogf
7
9 #include <adime.h>
10 int adime_dialogf(const char *title, int x, y, w, const char *format,
13 ...);
14
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 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 %bool[]
34 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 %greybool[]
40 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 %double[x,y], %float[x,y],
46 %int[x,y], %short[x,y], %char[x,y],
48 %uint[x,y], %ushort[x,y], %uchar[x,y],
50 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 %pdouble[x,y], %pfloat[x,y],
58 %pint[x,y], %pshort[x,y], %pchar[x,y],
60 %puint[x,y], %pushort[x,y], %puchar[x,y],
62 "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 %string[bytes]
69 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 %filename[len,extension,title]
77 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 %list[lines,list]
92 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 %vlist[lines]
102 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 %datafile[lines,types]
111 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 "%datafile[7,BMP ;RLE ;XCMP; CMP]"
122 %wlist[lines,title,list]
125 %wvlist[lines,title]
127 %wdatafile[lines,title,types]
129 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 %nothing[]
136 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 %line[]
142 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 %button[text]
149 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 int my_callback(DIALOG *d);
155 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 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 %buttonrow[BUTTONS]
171 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 int my_callback(DIALOG *d, int n);
179 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 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 %buttonrow[OK;CTRL+O;ENTER,Cancel;ESC,Help;F1;ALT+H]
191 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 %dialogf[buttontext]
209 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 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 %vdialogf[buttontext]
229 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 %chain[]
235 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 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 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 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 An example may help to clarify things (see also the programs in the
258 examples directory):
259 char name_buffer[1024] = "";
261 int age = 20;
262 int shoe_size = 40;
263 int married = 0;
264 char filename_buffer[1024] = "";
265 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
282 adime_init(3), adime_vdialogf(3), adime_bmp(3), adime_font(3),
283 adime_va_list(3)
284Adime version 2.2.1 adime_dialogf(3)