~mdw / ssr / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
Initial revision
[ssr] / 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
The Straylight Source Distribution (obsolete software for RISC OS)