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