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

   1 ;
   2 ; menuDefs.sh
   3 ;
   4 ; Constant definitions and macros for dealing with menus
   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 ; Macros provided:
  30 ;
  31 ;   BITSPEC
  32 ;   SETBIT
  33 ;   NEWITEM
  34 ;   MENU
  35 ;   MENUI
  36 ;   TEAROFF
  37 ;   TEAROFFI
  38 ;   R12DATA
  39 ;   MAKEME
  40 ;   MHEIGHT
  41 ;   GLOBALM
  42 ;   ITEM
  43 ;   ITEWI
  44 ;   SHADE
  45 ;   ISHADE
  46 ;   SWITCH
  47 ;   RADIO
  48 ;   SPRITE
  49 ;   HALFSZ
  50 ;   SUBWARN
  51 ;   SUBMENU
  52 ;   NOWARN
  53 ;   RULEOFF
  54 ;   MENUEND
  55
  56                 [       :LNOT::DEF:menuDefs__dfn
  57                 GBLL    menuDefs__dfn
  58
  59 ;+              LIB     sapphire:^.bsh.menuDefs
  60
  61 ;----- Constants for menus --------------------------------------------------
  62 ;
  63 ; In the descriptions of flags below, the data required in the packed menu
  64 ; definition is shown in the comments.  Insert items in the order of the
  65 ; bit precedences of the flags.
  66 ;
  67 ; Note -- a (*) following a description means the flag is only supported by
  68 ; tms (the tearoff system), and a (+) means that the flag is only supported
  69 ; by menu (the WIMP system).
  70
  71 ; --- Flags for menu titles and items ---
  72
  73 mFlag_indirect  EQU     (1<<0)                  ;Data string is indirect
  74                                                 ;+0 == offset of text pointer
  75                                                 ;+4
  76
  77 mFlag_R12       EQU     (1<<16)                 ;Use R12 for writable data
  78                                                 ;+0
  79
  80 mFlag_noTrans   EQU     (1<<19)                 ;Don't translate messages
  81                                                 ;+0
  82
  83 ; --- Menu title flags ---
  84
  85 mFlag_tearoff   EQU     (1<<1)                  ;Menu may be torn off (*)
  86                                                 ;+0
  87
  88 mFlag_makeMe    EQU     (1<<2)                  ;Menu recreated by client (+)
  89                                                 ;+0 == pointer to recreate fn
  90                                                 ;+4
  91
  92 mFlag_maxHeight EQU     (1<<3)                  ;Menu has a max height (*)
  93                                                 ;+0 == max height in OS units
  94                                                 ;+4
  95
  96 mFlag_global    EQU     (1<<4)                  ;Menu is `global' (*)
  97                                                 ;+0
  98
  99 ; --- Menu item flags ---
 100
 101 mFlag_shortCut  EQU     (1<<1)                  ;Item has a shortcut
 102                                                 ;+0 == shortcut key number
 103                                                 ;+4
 104
 105 mFlag_iShortCut EQU     (1<<2)                  ;Item has indirected shortcut
 106                                                 ;+0 == offset of key number
 107                                                 ;+4
 108
 109 mFlag_shade     EQU     (1<<3)                  ;Item may be shaded
 110                                                 ;+0 == bitspec of shade bit
 111                                                 ;+4
 112
 113 mFlag_invShade  EQU     (1<<4)                  ;Item may be unshaded
 114                                                 ;+0 == bitspec of unshade bit
 115                                                 ;+4
 116
 117 mFlag_switch    EQU     (1<<5)                  ;Item is a switch (tickable)
 118                                                 ;+0 == bitspec of tick bit
 119                                                 ;+4
 120
 121 mFlag_radio     EQU     (1<<6)                  ;Item is a radio button
 122                                                 ;+0 == offset of grp selector
 123                                                 ;+4 == number of item in grp
 124                                                 ;+8
 125
 126 mFlag_sprite    EQU     (1<<7)                  ;Item contains a sprite (*)
 127                                                 ;For WIMP menus:
 128                                                 ;+0 == ptr to validation str
 129                                                 ;+4
 130                                                 ;For TMS menus:
 131                                                 ;+0 == offset of name pointer
 132                                                 ;+4 == sprite area (-1==res)
 133                                                 ;+8
 134
 135 mFlag_halfSize  EQU     (1<<8)                  ;Display sprite half sized
 136                                                 ;+0
 137
 138 mFlag_subWarn   EQU     (1<<9)                  ;Make event on opening sub
 139                                                 ;+0
 140
 141 mFlag_subMenu   EQU     (1<<10)                 ;Item has a submenu
 142                                                 ;+0 == pointer to submenu def
 143                                                 ;+4
 144
 145 mFlag_noWarn    EQU     (1<<17)                 ;Don't open sub when shaded
 146                                                 ;+0
 147
 148 mFlag_ruleOff   EQU     (1<<18)                 ;Rule off after the item
 149                                                 ;+0
 150
 151 mFlag_end       EQU     (1<<31)                 ;There are no more items
 152                                                 ;+0
 153
 154 ; --- Event codes ---
 155 ;
 156 ; Event codes are returned in R0, with R1 being the item number within
 157 ; the packed menu definition, indexed from 0.
 158 ;
 159 ; Note: mEvent_deleted is only sent to the topmost menu title by the
 160 ; standard menu system, but is sent to the titles of all menus being closed
 161 ; by TMS.  If you are converting from one to the other, bear this in mind.
 162
 163 mEvent_select   EQU     0                       ;The user chose a menu item
 164                                                 ;R1 == item number
 165                                                 ;R2 == address of packed def
 166
 167 mEvent_subMenu  EQU     1                       ;A submenu is about to open
 168                                                 ;R1 == item number
 169
 170 mEvent_deleted  EQU     2                       ;A menu has just closed
 171
 172 mEvent_help     EQU     3                       ;Help is wanted for an item
 173                                                 ;R1 == item number
 174                                                 ;R2 == address of packed def
 175
 176 ;----- Menu creation macros -------------------------------------------------
 177
 178 ; --- Note to reader ---
 179 ;
 180 ; These macros make a lot of use of private constants and variables.  Try to
 181 ; avoid examining these too closely, because you'll probably get lost.
 182
 183 ; --- Set up the variables ---
 184
 185                 GBLA    md__i
 186 md__i           SETA    0
 187                 GBLA    md__f
 188 md__f           SETA    0
 189
 190 ; --- Macro: BITSPEC ---
 191 ;
 192 ; Arguments:    offset == offset into workspace of target word
 193 ;               bit == bitmask with a 1 in the position of the bit
 194 ;
 195 ; Use:          Assembles a bit specification referencing the described bit.
 196 ;               The bit is described by a mask word rather than a bit
 197 ;               position, because it is expected that you will already have
 198 ;               set up constants for bit masks.
 199
 200                 MACRO
 201                 BITSPEC $offset,$bit
 202
 203                 LCLA    bn
 204 bn              SETA    0
 205                 LCLA    bv
 206 bv              SETA    $bit
 207                 [       bv = 0
 208                 !       1,"Bit mask is 0 in BITSPEC"
 209                 ]
 210
 211                 WHILE   (bv :AND: 1)=0
 212 bn              SETA    bn+1
 213 bv              SETA    bv >> 1
 214                 WEND
 215
 216                 DCD     ($offset << 5) :OR: bn
 217                 MEND
 218
 219 ; --- Macro: SETBIT ---
 220 ;
 221 ; Arguments:    flag == which menu flag above to set
 222 ;
 223 ; Use:          Sets a bit within the current item or menu title's flags
 224 ;               word.  It ensures that items are inserted in the correct
 225 ;               order.
 226
 227                 MACRO
 228                 SETBIT  $flag
 229                 [       (md__f :AND: &ffff) >= $flag
 230                 !       1,"Flags built in bad order in menuDefs"
 231                 ]
 232 md__f           SETA    md__f :OR: $flag
 233                 MEND
 234
 235 ; --- Macro: NEWITEM ---
 236 ;
 237 ; Arguments:    --
 238 ;
 239 ; Use:          Starts a new menu item or menu title.  It also inserts a new
 240 ;               flags word in the current position.
 241
 242                 MACRO
 243 $label          NEWITEM
 244                 ALIGN
 245 $label
 246 md__F$md__i     EQU     md__f
 247 md__f           SETA    0
 248 md__i           SETA    md__i+1
 249                 DCD     md__F$md__i
 250                 MEND
 251
 252 ; --- Macro: MENU ---
 253 ;
 254 ; Arguments:    title == the menu's title string/message tag
 255 ;
 256 ; Use:          Creates a nonindirected menu title and starts a new menu.
 257
 258                 MACRO
 259 $label          MENU    $title
 260 $label          NEWITEM
 261                 [       :LEN:"$title">12
 262                 !       1,"Menu title too long"
 263                 ]
 264                 DCB     "$title",0
 265                 ALIGN
 266                 MEND
 267
 268 ; --- Macro: MENUI ---
 269 ;
 270 ; Arguments:    title == offset to title pointer in client's workspace
 271 ;
 272 ; Use:          Creates an indirected menu title and starts a new menu.
 273
 274                 MACRO
 275 $label          MENUI   $title
 276 $label          NEWITEM
 277                 SETBIT  mFlag_indirect
 278                 DCD     $title
 279                 MEND
 280
 281 ; --- Macro: TEAROFF ---
 282 ;
 283 ; Arguments:    title == menu's title string/message tag
 284 ;
 285 ; Use:          Creates a nonindirected tearoff menu title and starts a new
 286 ;               menu.
 287
 288                 MACRO
 289 $label          TEAROFF $title
 290 $label          NEWITEM
 291                 DCB     "$title",0
 292                 ALIGN
 293                 SETBIT  mFlag_tearoff
 294                 MEND
 295
 296 ; --- Macro: TEARI ---
 297 ;
 298 ; Arguments:    title == offset to title pointer in client's workspace
 299 ;
 300 ; Use:          Creates an indirected tearoff menu title and starts a new
 301 ;               menu.
 302
 303                 MACRO
 304 $label          TEARI   $title
 305 $label          NEWITEM
 306                 SETBIT  mFlag_indirect
 307                 DCD     $title
 308                 SETBIT  mFlag_tearoff
 309                 MEND
 310
 311 ; --- Macro: R12DATA ---
 312 ;
 313 ; Arguments:    --
 314 ;
 315 ; Use:          Sets the current menu item or menu title to use the client's
 316 ;               R12 pointer rather than its R10 pointer for workspace.
 317
 318                 MACRO
 319                 R12DATA
 320                 SETBIT  mFlag_R12
 321                 MEND
 322
 323 ; --- Macro: NOTRANS ---
 324 ;
 325 ; Arguments:    --
 326 ;
 327 ; Use:          Disables message translation of the current item or menu
 328 ;               title.  This is useful if you're building the item or title
 329 ;               text dynamically.
 330
 331                 MACRO
 332                 NOTRANS
 333                 SETBIT  mFlag_noTrans
 334                 MEND
 335
 336 ; --- Macro: MAKEME ---
 337 ;
 338 ; Arguments:    makeProc == pointer to procedure which will remake the menu
 339 ;
 340 ; Use:          Sets the current menu to require being remade from scratch
 341 ;               when being updated (e.g. after an item is selected).
 342
 343                 MACRO
 344                 MAKEME  $makeProc
 345                 SETBIT  mFlag_makeMe
 346                 DCD     $makeProc
 347                 MEND
 348
 349 ; --- Macro: MHEIGHT ---
 350 ;
 351 ; Arguments:    height == maximum permitted height for menu in OS units
 352 ;
 353 ; Use:          Sets the menu's maximum allowable height.
 354
 355                 MACRO
 356                 MHEIGHT $height
 357                 SETBIT  mFlag_maxHeight
 358                 DCD     $height
 359                 MEND
 360
 361 ; --- Macro: GLOBALM ---
 362 ;
 363 ; Arguments:    --
 364 ;
 365 ; Use:          Sets the menu's maximum allowable height.
 366
 367                 MACRO
 368                 GLOBALM
 369                 SETBIT  mFlag_global
 370                 MEND
 371
 372 ; --- Macro: ITEM ---
 373 ;
 374 ; Arguments:    text == item's text string/message tag
 375 ;
 376 ; Use:          Creates a new nonindirected menu item.
 377
 378                 MACRO
 379 $label          ITEM    $text
 380 $label          NEWITEM
 381                 DCB     "$text",0
 382                 ALIGN
 383                 MEND
 384
 385 ; --- Macro: ITEMI ---
 386 ;
 387 ; Arguments:    text == offset of pointer to menu text
 388 ;
 389 ; Use:          Creates a new indirected menu item
 390
 391                 MACRO
 392 $label          ITEMI   $text
 393 $label          NEWITEM
 394                 SETBIT  mFlag_indirect
 395                 DCD     $text
 396                 MEND
 397
 398 ; --- Macro: SHADE ---
 399 ;
 400 ; Arguments:    $offset,$bit == bitspec of item's `shaded' bit
 401 ;
 402 ; Use:          Sets the current item to be shadable.
 403
 404                 MACRO
 405                 SHADE   $offset,$bit
 406                 SETBIT  mFlag_shade
 407                 BITSPEC $offset,$bit
 408                 MEND
 409
 410 ; --- Macro: ISHADE ---
 411 ;
 412 ; Arguments:    offset,$bit == bitspec of item's `unshaded' bit
 413 ;
 414 ; Use:          Sets the current item to be inverse shadable.
 415
 416                 MACRO
 417                 ISHADE  $offset,$bit
 418                 SETBIT  mFlag_invShade
 419                 BITSPEC $offset,$bit
 420                 MEND
 421
 422 ; --- Macro: SWITCH ---
 423 ;
 424 ; Arguments:    offset,$bit == bitspec of item's `ticked' bit
 425 ;
 426 ; Use:          Sets the current item to be tickable.
 427
 428                 MACRO
 429                 SWITCH  $offset,$bit
 430                 SETBIT  mFlag_switch
 431                 BITSPEC $offset,$bit
 432                 MEND
 433
 434 ; --- Macro: RADIO ---
 435 ;
 436 ; Arguments:    group == offset of this item's radio group selector
 437 ;               selector == value of selector to blob this item
 438 ;
 439 ; Use:          Marks this item as a radio item, so that it is blobbed (or
 440 ;               ticked under the WIMP menu system) when the selector in the
 441 ;               client's workspace matches the item's selector.
 442
 443                 MACRO
 444                 RADIO   $group,$selector
 445                 SETBIT  mFlag_radio
 446                 DCD     $group,$selector
 447                 MEND
 448
 449 ; --- Macro: SPRITE ---
 450 ;
 451 ; Arguments:    sprite == EITHER address of validation string, OR offset of
 452 ;                 sprite name pointer (if area argument given)
 453 ;               area == (optional) sprite area, or -1 for resspr_area
 454 ;
 455 ; Use:          Adds a sprite to the menu item definition.
 456
 457                 MACRO
 458                 SPRITE  $sprite,$area
 459                 SETBIT  mFlag_sprite
 460                 DCD     $sprite
 461                 [ "$area"<>""
 462                 DCD     $area
 463                 ]
 464                 MEND
 465
 466 ; --- Macro: HALFSZ ---
 467 ;
 468 ; Arguments:    --
 469 ;
 470 ; Use:          Sets the item to display its sprite at half size
 471
 472                 MACRO
 473                 HALFSZ
 474                 SETBIT  mFlag_halfSize
 475                 MEND
 476
 477 ; --- Macro: SUBWARN ---
 478 ;
 479 ; Arguments:    --
 480 ;
 481 ; Use:          Sets the item to generate submenu warnings when its submenu
 482 ;               arrow is pointed at.
 483
 484                 MACRO
 485                 SUBWARN
 486                 SETBIT  mFlag_subWarn
 487                 MEND
 488
 489 ; --- Macro: SUBMENU ---
 490 ;
 491 ; Arguments:    subMenu == pointer to packed definition of the submenu
 492 ;               handler == pointer to handler routine
 493 ;
 494 ; Use:          Attaches the given menu as a submenu of this item.
 495
 496                 MACRO
 497                 SUBMENU $subMenu,$handler
 498                 SETBIT  mFlag_subMenu
 499                 DCD     $subMenu,$handler
 500                 MEND
 501
 502 ; --- Macro: NOWARN ---
 503 ;
 504 ; Arguments:    --
 505 ;
 506 ; Use:          Prevents this item from returning submenu events if it is
 507 ;               shaded.
 508
 509                 MACRO
 510                 NOWARN
 511                 SETBIT  mFlag_noWarn
 512                 MEND
 513
 514 ; --- Macro: RULEOFF ---
 515 ;
 516 ; Arguments:    --
 517 ;
 518 ; Use:          Inserts a ruleoff after the current item, assuming there are
 519 ;               some more items after it.
 520
 521                 MACRO
 522                 RULEOFF
 523                 SETBIT  mFlag_ruleOff
 524                 MEND
 525
 526 ; --- Macro: MENUEND ---
 527 ;
 528 ; Arguments:    --
 529 ;
 530 ; Use:          Finishes off the current menu.
 531
 532                 MACRO
 533                 MENUEND
 534 md__F$md__i     EQU     md__f
 535 md__f           SETA    0
 536 md__i           SETA    md__i+1
 537                 DCD     mFlag_end
 538                 MEND
 539
 540                 ]
 541
 542 ;----- That's all, folks ----------------------------------------------------
 543
 544                 END