2ee739cc |
1 | /* |
2 | * dbox.h |
3 | * |
4 | * [Generated from dbox, 07 February 1998] |
5 | */ |
6 | |
7 | #if !defined(__CC_NORCROFT) || !defined(__arm) |
8 | #error You must use the Norcroft ARM Compiler for Sapphire programs |
9 | endif |
10 | |
11 | #pragma include_only_once |
12 | #pragma force_top_level |
13 | |
14 | #ifndef __dbox_h |
15 | #define __dbox_h |
16 | |
17 | #ifndef __sapphire_h |
18 | #include "sapphire.h" |
19 | #endif |
20 | |
21 | /*----- Licensing note ----------------------------------------------------* |
22 | * |
23 | * This file is part of Straylight's Sapphire library. |
24 | * |
25 | * Sapphire is free software; you can redistribute it and/or modify |
26 | * it under the terms of the GNU General Public License as published by |
27 | * the Free Software Foundation; either version 2, or (at your option) |
28 | * any later version. |
29 | * |
30 | * Sapphire is distributed in the hope that it will be useful, |
31 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
32 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
33 | * GNU General Public License for more details. |
34 | * |
35 | * You should have received a copy of the GNU General Public License |
36 | * along with Sapphire. If not, write to the Free Software Foundation, |
37 | * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
38 | */ |
39 | |
40 | /*----- Overview ----------------------------------------------------------* |
41 | * |
42 | * Functions provided: |
43 | * |
44 | * dbox_create |
45 | * dbox_fromEmbedded |
46 | * dbox_fromDefn |
47 | * dbox_destroy |
48 | * dbox_init |
49 | * dbox_open |
50 | * dbox_close |
51 | * dbox_writePos |
52 | * dbox_select |
53 | * dbox_shade |
54 | * dbox_selectMany |
55 | * dbox_shadeMany |
56 | * dbox_isSelected |
57 | * dbox_radio |
58 | * dbox_slab |
59 | * dbox_unslab |
60 | * dbox_setField |
61 | * dbox_getField |
62 | * dbox_eventHandler |
63 | * dbox_renderTitle |
64 | * dbox_setEmbeddedTitle |
65 | * dbox_setClickDrag |
66 | * dbox_hasTitle |
67 | * dbox_window |
68 | * dbox_help |
69 | */ |
70 | |
71 | /* --- dbox_create --- * |
72 | * |
73 | * On entry: R0 == pointer to dialogue template name |
74 | * |
75 | * On exit: R0 == dialogue box handle for the dialogue |
76 | * May return an error |
77 | * |
78 | * Use: Creates a dialogue box from a template definition. |
79 | */ |
80 | |
81 | extern routine dbox_create; |
82 | |
83 | /* --- dbox_fromEmbedded --- * |
84 | * |
85 | * On entry: R0 == pointer to an embedded template |
86 | * |
87 | * On exit: R0 == dialogue box handle |
88 | * May return an error |
89 | * |
90 | * Use: Creates a dialogue box from an embedded template definition. |
91 | */ |
92 | |
93 | extern routine dbox_fromEmbedded; |
94 | |
95 | /* --- dbox_fromDefn --- * |
96 | * |
97 | * On entry: R0 == pointer to a window definition |
98 | * |
99 | * On exit: R0 == dialogue box handle for the dialogue |
100 | * May return an error |
101 | * |
102 | * Use: Creates a dialogue box from an immediate window definition, |
103 | * rather than a template. There are several things you need |
104 | * to be aware of when you use this call to create a dialogue |
105 | * box: |
106 | * |
107 | * * The window definition is not copied, but used directly |
108 | * for the duration the dialogue box exists. It must |
109 | * not move for this duration. When the dialogue is |
110 | * destroyed, you can release the memory for the definition, |
111 | * although this is your responsibility. |
112 | * |
113 | * * The indirected data is not copied either, so you'll have |
114 | * to copy it yourself if you want multiple dialogues from |
115 | * the same window definition. |
116 | * |
117 | * * The window definition and the indirected data must both |
118 | * be writable. |
119 | */ |
120 | |
121 | extern routine dbox_fromDefn; |
122 | |
123 | /* --- dbox_destroy --- * |
124 | * |
125 | * On entry: R0 == dialogue box handle |
126 | * |
127 | * On exit: -- |
128 | * |
129 | * Use: Destroys a dialogue box, freeing all the memory it took |
130 | * up etc. |
131 | */ |
132 | |
133 | extern routine dbox_destroy; |
134 | |
135 | /* --- dbox_init --- * |
136 | * |
137 | * On entry: -- |
138 | * |
139 | * On exit: -- |
140 | * |
141 | * Use: Initialises the dbox system. |
142 | */ |
143 | |
144 | extern routine dbox_init; |
145 | |
146 | /* --- dbox_open --- * |
147 | * |
148 | * On entry: R0 == dialogue box handle |
149 | * R1 == how to open the dialogue box |
150 | * Other registers depend on R1, and are described at the end |
151 | * of this header file |
152 | * |
153 | * On exit: -- |
154 | * |
155 | * Use: Displays the dialogue box on the screen in the given manner. |
156 | */ |
157 | |
158 | extern routine dbox_open; |
159 | |
160 | /* --- dbox_close --- * |
161 | * |
162 | * On entry: R0 == dialogue box handle |
163 | * |
164 | * On exit: -- |
165 | * |
166 | * Use: Closes a dialogue box, by clearing the current menu if |
167 | * necessary. |
168 | */ |
169 | |
170 | extern routine dbox_close; |
171 | |
172 | /* --- dbox_writePos --- * |
173 | * |
174 | * On entry: R0 == dialogue box handle |
175 | * |
176 | * On exit: -- |
177 | * |
178 | * Use: Saves the dialogue's current position so that it will be |
179 | * opened here the next time it is created. If the dialogue |
180 | * box was created from a template, the template is updated. |
181 | * Otherwise, the new state is written back to the definition |
182 | * supplied to dbox_fromDefn. |
183 | */ |
184 | |
185 | extern routine dbox_writePos; |
186 | |
187 | /* --- dbox_select --- * |
188 | * |
189 | * On entry: R0 == dialogue box handle |
190 | * R1 == icon number |
191 | * R2 == 0 to deselect the icon, 1 to select it, 2 to toggle |
192 | * its current selected state |
193 | * |
194 | * On exit: -- |
195 | * |
196 | * Use: Selects or deselects the specified icon in the Acorn sense |
197 | * (i.e. by flipping its selected bit). The state is only |
198 | * changed if required, to reduce flicker. |
199 | */ |
200 | |
201 | extern routine dbox_select; |
202 | |
203 | /* --- dbox_shade --- * |
204 | * |
205 | * On entry: R0 == dialogue box handle |
206 | * R1 == icon number |
207 | * R2 == 0 to unshade the icon, 1 to shade it, 2 to toggle its |
208 | * current shaded state |
209 | * |
210 | * On exit: -- |
211 | * |
212 | * Use: Makes the icon look dimmer, to indicate that it is not |
213 | * available. It uses its own shading algorithms, rather than |
214 | * the WindowManager's, so there are some things you must watch |
215 | * out for: |
216 | * |
217 | * * Don't use any other method of shading icons |
218 | * |
219 | * * Don't assume that a shaded icon isn't going to give you |
220 | * events. At the user level, this should have been tidied |
221 | * up, but at the Sapphire level, it's still a problem. |
222 | * There is a routine in winUtils which will tell you if an |
223 | * icon is shaded. |
224 | * |
225 | * This routine has been written so that it only flickers icons |
226 | * when they actually need it. |
227 | */ |
228 | |
229 | extern routine dbox_shade; |
230 | |
231 | /* --- dbox_selectMany --- * |
232 | * |
233 | * On entry: R0 == dialogue box handle |
234 | * R1 == pointer to icon handle list, -1 terminated |
235 | * R2 == select action (0 == unselect, 1 == select, 2 == toggle) |
236 | * |
237 | * On exit: -- |
238 | * |
239 | * Use: Changes the select state of a group of icons. |
240 | */ |
241 | |
242 | extern routine dbox_selectMany; |
243 | |
244 | /* --- dbox_shadeMany --- * |
245 | * |
246 | * On entry: R0 == dialogue box handle |
247 | * R1 == pointer to icon handle list, -1 terminated |
248 | * R2 == shade action (0 == unshade, 1 == shade, 2 == toggle) |
249 | * |
250 | * On exit: -- |
251 | * |
252 | * Use: Changes the shade state of a group of icons. |
253 | */ |
254 | |
255 | extern routine dbox_shadeMany; |
256 | |
257 | /* --- dbox_isSelected --- * |
258 | * |
259 | * On entry: R0 == dialogue box handle |
260 | * R1 == icon number |
261 | * |
262 | * On exit: CS if the icon is selected, CC otherwise |
263 | * |
264 | * Use: Returns whether an icon is currently selected. |
265 | */ |
266 | |
267 | extern routine dbox_isSelected; |
268 | |
269 | /* --- dbox_radio --- * |
270 | * |
271 | * On entry: R0 == dialogue box handle |
272 | * R1 == icon handle |
273 | * |
274 | * On exit: -- |
275 | * |
276 | * Use: Checks to see if the icon is a radio button as defined by |
277 | * Sapphire, i.e. button type 3 (debounced) and non-zero ESG. |
278 | * If it is, it selects it, and deselects all other icons with |
279 | * this ESG. |
280 | */ |
281 | |
282 | extern routine dbox_radio; |
283 | |
284 | /* --- dbox_slab --- * |
285 | * |
286 | * On entry: R0 == dialogue box handle |
287 | * R1 == icon handle |
288 | * |
289 | * On exit: May return an error |
290 | * |
291 | * Use: Slabs an icon in properly, to give visual feedback when you |
292 | * click it. |
293 | */ |
294 | |
295 | extern routine dbox_slab; |
296 | |
297 | /* --- dbox_unslab --- * |
298 | * |
299 | * On entry: -- |
300 | * |
301 | * On exit: CS if there are no more slabbed icons after this one, CC |
302 | * if there are more left. |
303 | * |
304 | * Use: Unslabs an icon slabbed with dbox_slab. Icons are unslabbed |
305 | * in reverse order to that in which they were slabbed. The |
306 | * carry flag is returned as an indication of whether there |
307 | * are any more icons left in the list -- you can unslab all |
308 | * icons in one go by doing: |
309 | * |
310 | * BL dbox_unslab |
311 | * SUBCC PC,PC,#12 ;Avoids a label! |
312 | * |
313 | * It is recommended that, if you are going to close a window, |
314 | * you unslab icons within it *after* you close, but before you |
315 | * actually destroy it, e.g. |
316 | * |
317 | * LDR R0,my_dbox |
318 | * BL dbox_close |
319 | * BL dbox_unslab |
320 | * BL dbox_destroy |
321 | */ |
322 | |
323 | extern routine dbox_unslab; |
324 | |
325 | /* --- dbox_setField --- * |
326 | * |
327 | * On entry: R0 == dialogue box handle |
328 | * R1 == icon number to write to (may be -1 for title) |
329 | * flags in top byte if not -1: |
330 | * dbFlag_dots (bit 31) == add `...' if text overflows |
331 | * R2 == pointer to string to use |
332 | * |
333 | * On exit: -- |
334 | * |
335 | * Use: Writes the string specified into the indirection buffer |
336 | * for the given icon. If the icon is not indirected, an |
337 | * error is generated. If the indirected buffer is too small, |
338 | * the string is shortened by chopping off the beginning or |
339 | * the end, according to the setting of the icon's right |
340 | * justify flag. |
341 | * |
342 | * The icon is only flickered if the text has actually changed. |
343 | * The caret is moved correctly if it is within the icon to |
344 | * prevent it `falling off' the end and deleting the validation |
345 | * string, or being positioned incorrectly in centred icons if |
346 | * the length changes. |
347 | * |
348 | * Note that this routine requires a string to already be in |
349 | * the buffer, and doesn't perform any substitution or other |
350 | * transformations. This helps to prevent buffer full errors |
351 | * and similar problems. |
352 | */ |
353 | |
354 | extern routine dbox_setField; |
355 | |
356 | /* --- dbox_getField --- * |
357 | * |
358 | * On entry: R0 == dialogue box handle |
359 | * R1 == icon number to interrogate |
360 | * |
361 | * On exit: R0, R1 preserved |
362 | * R2 == pointer to the icon text |
363 | * |
364 | * Use: Returns a pointer to the text associated with an icon. |
365 | * Note that if the icon is *not* indirected, the text will |
366 | * be copied into the scratchpad. Otherwise you get a pointer |
367 | * to the actual indirected data. You shouldn't write to the |
368 | * string returned at all -- dbox_setField is specially |
369 | * designed to do that sort of thing very well (i.e. not |
370 | * flickering the text unless it has to, truncating if it's too |
371 | * long, and handling the caret correctly). You *are* allowed |
372 | * to zero terminate the string if you want to, though. |
373 | * |
374 | * Despite all the PRM's assurances to the contrary, chances |
375 | * are the text will be terminated by some weird control char, |
376 | * so you'll have to handle this, and not just assume it's |
377 | * going to be null-terminated. |
378 | * |
379 | * Note: The indirected case is immensely quick -- just load a |
380 | * pointer. The non-indirected case has been optimised as much |
381 | * as possible. |
382 | */ |
383 | |
384 | extern routine dbox_getField; |
385 | |
386 | /* --- dbox_eventHandler --- * |
387 | * |
388 | * On entry: R0 == dialogue box handle |
389 | * R1 == pointer to handler routine |
390 | * R2 == value to pass to handler in R10 |
391 | * R3 == value to pass to handler in R12 |
392 | * |
393 | * On exit: R0 preserved |
394 | * R1 == pointer to old handler |
395 | * R2 == old R10 value |
396 | * R3 == old R12 value |
397 | * |
398 | * Use: Sets up an event handler for a dialogue box, and returns |
399 | * the previous one. If the pointer to handler is 0, there is |
400 | * no dialogue box event handler. |
401 | */ |
402 | |
403 | extern routine dbox_eventHandler; |
404 | |
405 | /* --- dbox_renderTitle --- * |
406 | * |
407 | * On entry: R0 == dialogue box handle |
408 | * R1 == pointer to redraw block |
409 | * |
410 | * On exit: -- |
411 | * |
412 | * Use: Renders a dialogue box's embedded title if there is one. |
413 | */ |
414 | |
415 | extern routine dbox_renderTitle; |
416 | |
417 | /* --- dbox_setEmbeddedTitle --- * |
418 | * |
419 | * On entry: R0 == dialogue box handle |
420 | * R1 == icon which should contain the embedded title |
421 | * |
422 | * On exit: -- |
423 | * |
424 | * Use: Declares a given dialogue box as requiring an embedded title |
425 | * (rather than the one the WindowManager put on). |
426 | */ |
427 | |
428 | extern routine dbox_setEmbeddedTitle; |
429 | |
430 | /* --- dbox_setClickDrag --- * |
431 | * |
432 | * On entry: R0 == dialogue box handle |
433 | * |
434 | * On exit: -- |
435 | * |
436 | * Use: Sets a given dialogue box so that the user can move it by |
437 | * dragging from any part of the window, not just the title |
438 | * bar. |
439 | */ |
440 | |
441 | extern routine dbox_setClickDrag; |
442 | |
443 | /* --- dbox_hasTitle --- * |
444 | * |
445 | * On entry: R0 == dialogue box handle |
446 | * |
447 | * On exit: CS if the dialogue box has a title bar, CC if not |
448 | * |
449 | * Use: Informs the caller whether the dialogue box has a title bar. |
450 | * This is mainly useful for other library sections which |
451 | * conditionally add in embedded titles etc. |
452 | */ |
453 | |
454 | extern routine dbox_hasTitle; |
455 | |
456 | /* --- dbox_window --- * |
457 | * |
458 | * On entry: R0 == dialogue box handle |
459 | * |
460 | * On exit: R0 == the dialogue box's window handle |
461 | * |
462 | * Use: Returns the Wimp window handle associated with a dialogue |
463 | * box. This may be useful if you want to perform lowlevel |
464 | * Wimp operation on it, or to subclass it using win. |
465 | */ |
466 | |
467 | extern routine dbox_window; |
468 | |
469 | /* --- dbox_help --- * |
470 | * |
471 | * On entry: -- |
472 | * |
473 | * On exit: -- |
474 | * |
475 | * Use: Adds a help line to the current help message, read by |
476 | * scanning the icon to which the help was sent for an `H' |
477 | * validation string. |
478 | */ |
479 | |
480 | extern routine dbox_help; |
481 | |
482 | /*----- Useful constants --------------------------------------------------*/ |
483 | |
484 | /* --- Ways of opening dialogue boxes --- */ |
485 | |
486 | #define dbOpen_current 0 |
487 | #define dbOpen_centre 1 |
488 | #define dbOpen_pointer 2 |
489 | #define dbOpen_givenY 3 |
490 | #define dbOpen_givenXY 4 |
491 | |
492 | #define dbOpen_trans (0x00) |
493 | #define dbOpen_persist (0x80) |
494 | #define dbOpen_nonSub (0x40) |
495 | |
496 | /* --- Dialogue box event codes --- */ |
497 | |
498 | #define dbEvent_close (-2) |
499 | |
500 | #define dbEvent_help (-3) |
501 | |
502 | #define dbEvent_OK (-4) |
503 | |
504 | #define dbEvent_cancel (-5) |
505 | |
506 | #define dbEvent_redraw (-6) |
507 | |
508 | #define dbEvent_menu (-7) |
509 | |
510 | #define dbEvent_drag (-8) |
511 | |
512 | #define dbEvent_save (-9) |
513 | |
514 | #define dbEvent_load (-10) |
515 | |
516 | #define dbEvent_key (-11) |
517 | |
518 | #define dbEvent_hint (-12) |
519 | |
520 | #define dbEvent_enter (-13) |
521 | |
522 | #define dbEvent_leave (-14) |
523 | |
524 | #define dbEvent_lifeCycle (-15) |
525 | |
526 | /* --- Life cycle codes --- */ |
527 | |
528 | #define dblc_create 0 |
529 | #define dblc_open 1 |
530 | #define dblc_close 2 |
531 | #define dblc_destroy 3 |
532 | |
533 | /* --- Other values --- */ |
534 | |
535 | #define dbFlag_dots ((1<<31)) |
536 | |
537 | /*----- That's all, folks -------------------------------------------------*/ |
538 | |
539 | #endif |