chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/csapph/h/dbox

   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