chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/sh/dbox

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