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

   1 ;
   2 ; viewer.sh
   3 ;
   4 ; Filer-like windows with re-arranging icons
   5 ;
   6 ; © 1995-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 ;  viewer_create
  32 ;  viewer_destroy
  33 ;  viewer_open
  34 ;  viewer_close
  35 ;  viewer_eventHandler
  36 ;  viewer_select
  37 ;  viewer_isSelected
  38 ;  viewer_selectAll
  39 ;  viewer_click
  40 ;  viewer_dragSelection
  41 ;  viewer_window
  42 ;  viewer_update
  43 ;  viewer_setTitle
  44 ;  viewer_rescan
  45
  46                 [       :LNOT::DEF:viewer__dfn
  47                 GBLL    viewer__dfn
  48
  49 ; --- viewer_create ---
  50 ;
  51 ; On entry:     R0 == pointer to a viewer definition block
  52 ;               R1 == pointer to a list
  53 ;               R2 == sprite area for window
  54 ;
  55 ; On exit:      R0 == viewer handle
  56 ;               May return an error
  57 ;
  58 ; Use:          Creates a viewer window.  The viewer definition block
  59 ;               contains various interesting bits of information about the
  60 ;               viewer which are likely to be known at assembly time:
  61 ;
  62 ;               (word)   address of a list manager definition block
  63 ;               (word)   address of a shape handler function (or 0)
  64 ;               (word)   standard width of icons
  65 ;               (word)   standard height of icons
  66 ;               (string) banner text message tag, or empty
  67 ;
  68 ;               The shape function is used to allow viewer icons to have a
  69 ;               non-rectangular shape.  The function is called with a reason
  70 ;               code in R0; entry and exit conditions depend on this:
  71 ;
  72 ;                                                       vwShape_size
  73 ;               On entry
  74 ;                 R1 == pointer to list item
  75 ;                 R2 == standard width of icon
  76 ;                 R3 == standard height of icon
  77 ;
  78 ;               On exit
  79 ;                 R2 == width of this icon
  80 ;                 R3 == height of this icon
  81 ;
  82 ;               Use
  83 ;                 This routine is used to find the actual size of an icon.
  84 ;                 The icons are aligned on a grid according to the largest
  85 ;                 one: this routine is used to find out which one that is.
  86 ;
  87 ;                                                       vwShape_intersects
  88 ;               On entry
  89 ;                 R1 == pointer to list item
  90 ;                 R2 == address of bounding box of this icon
  91 ;                 R3 == address of bounding box to compare
  92 ;
  93 ;               On exit
  94 ;                 CS if boxes intersect, else CC
  95 ;
  96 ;               Use
  97 ;                 For detecting mouse clicks etc. on an icon.  viewer has
  98 ;                 already ensured that the box in R3 intersects with the
  99 ;                 bounding box, so for rectangular icons, you can just return
 100 ;                 with C set always.  This entry is provided so that you
 101 ;                 can check against the sprite and text of a text+sprite
 102 ;                 icon separately.
 103 ;
 104 ;               More reason codes may be added later; it will always be
 105 ;               sensible to return immediately preserving all registers and
 106 ;               flags.
 107
 108                 IMPORT  viewer_create
 109
 110 ; --- viewer_destroy ---
 111 ;
 112 ; On entry:     R0 == viewer handle
 113 ;
 114 ; On exit:      --
 115 ;
 116 ; Use:          Destroys a viewer, removing it from the screen etc.
 117
 118                 IMPORT  viewer_destroy
 119
 120 ; --- viewer_open ---
 121 ;
 122 ; On entry:     R0 == viewer handle
 123 ;               R1 == opening style
 124 ;               R2,R3 == extra arguments
 125 ;
 126 ; On exit:      --
 127 ;
 128 ; Use:          Opens a viewer window on the screen.
 129
 130                 IMPORT  viewer_open
 131
 132 ; --- viewer_close ---
 133 ;
 134 ; On entry:     R0 == viewer handle
 135 ;
 136 ; On exit:      --
 137 ;
 138 ; Use:          Closes a viewer window.
 139
 140                 IMPORT  viewer_close
 141
 142 ; --- viewer_eventHandler ---
 143 ;
 144 ; On entry:     R0 == viewer handle
 145 ;               R1 == pointer to event handler
 146 ;               R2 == value to pass in R10
 147 ;               R3 == value to pass in R12
 148 ;
 149 ; On exit:      R1-R3 == old values
 150 ;
 151 ; Use:          Sets up the event handle for the viewer.
 152
 153                 IMPORT  viewer_eventHandler
 154
 155 ; --- viewer_select ---
 156 ;
 157 ; On entry:     R0 == viewer handle
 158 ;               R1 == icon handle
 159 ;               R2 == 0 to unselect, 1 to select or 2 to toggle
 160 ;
 161 ; On exit:      --
 162 ;
 163 ; Use:          Selects an icon, or maybe unselects it.  Whatever, it doesn't
 164 ;               flicker if it doesn't need to.
 165
 166                 IMPORT  viewer_select
 167
 168 ; --- viewer_isSelected ---
 169 ;
 170 ; On entry:     R0 == viewer handle
 171 ;               R1 == icon handle
 172 ;
 173 ; On exit:      CS if icon is selected, else CC
 174 ;
 175 ; Use:          Informs you whether an icon is selected.
 176
 177                 IMPORT  viewer_isSelected
 178
 179 ; --- viewer_selectAll ---
 180 ;
 181 ; On entry:     R0 == viewer handle
 182 ;               R2 == 0 to deselect, or 1 to select
 183 ;
 184 ; On exit:      --
 185 ;
 186 ; Use:          Selects or deselects all the icons in a viewer.
 187
 188                 IMPORT  viewer_selectAll
 189
 190 ; --- viewer_click ---
 191 ;
 192 ; On entry:     R0 == viewer handle
 193 ;               R1 == icon handle (or 0)
 194 ;               R2 == mouse button state
 195 ;
 196 ; On exit:      --
 197 ;
 198 ; Use:          Handles a click, drag etc. according to the standard
 199 ;               selection model.
 200
 201                 IMPORT  viewer_click
 202
 203 ; --- viewer_dragSelection ---
 204 ;
 205 ; On entry:     R0 == viewer handle
 206 ;
 207 ; On exit:      --
 208 ;
 209 ; Use:          Starts a drag of the icons within the viewer.  When the drag
 210 ;               is finished, you get sent a vwEvent_dragged event.
 211
 212                 IMPORT  viewer_dragSelection
 213
 214 ; --- viewer_window ---
 215 ;
 216 ; On entry:     R0 == viewer handle
 217 ;
 218 ; On exit:      R0 == window handle
 219 ;
 220 ; Use:          Returns the window handle of the viewer.
 221
 222                 IMPORT  viewer_window
 223
 224 ; --- viewer_update ---
 225 ;
 226 ; On entry:     R0 == viewer handle
 227 ;               R1 == icon handle
 228 ;
 229 ; On exit:      --
 230 ;
 231 ; Use:          Updates (redraws) a given icon.
 232
 233                 IMPORT  viewer_update
 234
 235 ; --- viewer_setTitle ---
 236 ;
 237 ; On entry:     R0 == viewer handle
 238 ;               R1 == title string
 239 ;
 240 ; On exit:      --
 241 ;
 242 ; Use:          Sets the viewer window's title.
 243
 244                 IMPORT  viewer_setTitle
 245
 246 ; --- viewer_rescan ---
 247 ;
 248 ; On entry:     R0 == viewer handle
 249 ;
 250 ; On exit:      --
 251 ;
 252 ; Use:          Rescans all the icons in the viewer and forces a redraw,
 253 ;               in case icons have been added or deleted (or renamed).  Note
 254 ;               that the redraw is done *anyway* -- it's your responsibility
 255 ;               to avoid calling this routine when you don't need to.
 256
 257                 IMPORT  viewer_rescan
 258
 259 ;----- Shape function reason codes ------------------------------------------
 260
 261                 ^       0
 262 vwShape_size    #       1                       ;Read an icon's size
 263                                                 ;Entry: R1 == list item
 264                                                 ;       R2,R3 == std size
 265                                                 ;Exit:  R2,R3 == actual size
 266
 267 vwShape_intersects #    1                       ;Does icon intersect box?
 268                                                 ;Entry: R1 == list item
 269                                                 ;       R2 == ptr to icon box
 270                                                 ;       R3 == ptr to box
 271                                                 ;Exit:  CS if intersect
 272
 273 vwShape_slowBit #       1                       ;Does icon need slow redraw
 274                                                 ;Entry: R1 == list item
 275                                                 ;       R2 == ptr to icon box
 276                                                 ;       R3 == ptr to box
 277
 278 ;----- Viewer event codes ---------------------------------------------------
 279
 280                 ^       0
 281 vwEvent_close   #       1                       ;User has closed the window
 282
 283 vwEvent_click   #       1                       ;User has clicked an icon
 284                                                 ;R1 == icon handle (or 0)
 285                                                 ;R2 == mouse status
 286
 287 vwEvent_double  #       1                       ;User has double-clicked
 288                                                 ;R1 == icon handle (or 0)
 289                                                 ;R2 == mouse status
 290
 291 vwEvent_drag    #       1                       ;User has dragged the mouse
 292                                                 ;R1 == icon handle (or 0)
 293                                                 ;R2 == mouse status
 294
 295 vwEvent_menu    #       1                       ;User has clicked menu
 296                                                 ;R1 == icon handle (or 0)
 297                                                 ;R2 == mouse status
 298
 299 vwEvent_redraw  #       1                       ;Redraw a viewer icon
 300                                                 ;R1 == icon handle
 301                                                 ;R2 == pointer to coords blk
 302                                                 ;R3 == pointer to clip blk
 303                                                 ;R5,R6 == window origin
 304
 305 vwEvent_drop    #       1                       ;File dropped on the viewer
 306                                                 ;R1 == filetype of data
 307                                                 ;R2 == estimated size
 308                                                 ;R3 == address of filename
 309                                                 ;R4 == drop type
 310
 311 vwEvent_help    #       1                       ;Help request for the viewer
 312                                                 ;R1 == icon handle, or 0
 313
 314 vwEvent_key     #       1                       ;Key pressed
 315                                                 ;R1 == key code (translated)
 316                                                 ;Return CS if used, else CC
 317
 318 vwEvent_dragged #       1                       ;Icons dropped on a window
 319                                                 ;R1 == destination window
 320                                                 ;R2 == destination icon
 321
 322 vwEvent_sprite  #       1                       ;Return sprite name to use
 323                                                 ;Entry: R1 == icon handle
 324                                                 ;         (-1 for many)
 325                                                 ;Exit:  CS if sprite found,
 326                                                 ;       R0 == ptr to spr area
 327                                                 ;       R1 == pointer to name
 328                                                 ;       else CC
 329
 330 vwEvent_open    #       1                       ;The viewer has been moved
 331                                                 ;R1 == ptr to open/state blk
 332
 333 vwEvent_draw    #       1                       ;Fully draw icon
 334                                                 ;R1 == icon handle
 335                                                 ;R2 == pointer to coords blk
 336                                                 ;R3 == pointer to clip blk
 337                                                 ;R5,R6 == window origin
 338                                                 ;(Event only used by gallery)
 339
 340 vwEvent_unDraw  #       1                       ;Undraw temporary part
 341                                                 ;R1 == icon handle
 342                                                 ;R2 == pointer to coords blk
 343                                                 ;R3 == pointer to clip blk
 344                                                 ;R5,R6 == window origin
 345                                                 ;(Event only used by gallery)
 346
 347                 ; --- Drop event subreason codes ---
 348
 349                 ^       0
 350 vwDrop_save     #       1                       ;File from another app
 351 vwDrop_load     #       1                       ;File from filing system
 352
 353                 ]
 354
 355 ;----- That's all, folks ----------------------------------------------------
 356
 357                 END