~mdw / ssr / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
Initial revision
[ssr] / StraySrc / Libraries / Sapphire / s / help
1 ;
2 ; help.s
3 ;
4 ; Sending and handling help messages (MDW)
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 ;----- Standard header ------------------------------------------------------
28
29 GET libs:header
30 GET libs:swis
31
32 ;----- External dependencies ------------------------------------------------
33
34 GET sapphire:event
35 GET sapphire:idle
36 GET sapphire:msgs
37 GET sapphire:sapphire
38 GET sapphire:string
39
40 ;----- Main code ------------------------------------------------------------
41
42 AREA |Sapphire$$Code|,CODE,READONLY
43
44 ; --- help_init ---
45 ;
46 ; On entry: --
47 ;
48 ; On exit: --
49 ;
50 ; Use: Initialises the help system for use.
51
52 EXPORT help_init
53 help_init ROUT
54
55 STMFD R13!,{R0,R1,R12,R14} ;Save some registers
56
57 ; --- Make sure we're not going already ---
58
59 WSPACE help__wSpace ;Locate my workspace pointer
60 LDR R14,help__flags ;Get my flags word
61 TST R14,#hFlag__inited ;Am I initialised already?
62 LDMNEFD R13!,{R0,R1,R12,PC}^ ;Yes - return to caller
63 ORR R14,R14,#hFlag__inited ;I will be initialised soon
64 STR R14,help__flags ;Store the flags word back
65
66 ; --- Set up the workspace ---
67
68 MOV R14,#20 ;Start message size as 20
69 STR R14,help__message+0 ;Store this in the block
70 MOV R14,#0 ;No message to reply to
71 STR R14,help__msgTask ;Store in the your_ref field
72
73 ; --- Set up my prefilter ---
74
75 BL event_init ;Make sure event is awake
76 ADR R0,help__preFilter ;Point to the prefilter
77 MOV R1,R12 ;Pass along my workspace
78 BL event_preFilter ;Register it with event
79 ADR R0,help__postFilter ;Point to the postfilter
80 BL event_postFilter ;Register that with event too
81 LDMFD R13!,{R0,R1,R12,PC}^ ;Return to caller
82
83 LTORG
84
85 help__wSpace DCD 0
86
87 ; --- help__preFilter ---
88 ;
89 ; On entry: --
90 ;
91 ; On exit: --
92 ;
93 ; Use: Dispatches the currently waiting help reply, if there is
94 ; one. Also fakes hint requests and dispatches finished hints
95 ; to windows.
96
97 help__preFilter ROUT
98
99 STMFD R13!,{R14} ;Save a register
100
101 ; --- Check for hints first ---
102
103 LDR R14,help__flags ;Get my flags word
104 TST R14,#hFlag__hinted ;Do we have a waiting hint?
105 BNE %50help__preFilter ;Yes -- dispatch it to window
106 TST R14,#hFlag__hinting ;Do we need to make a hint?
107 BNE %60help__preFilter ;Yes -- build the block then
108
109 ; --- Otherwise, check for finished help messages ---
110
111 LDR R14,help__msgTask ;Get the your_ref for this
112 CMP R14,#0 ;Is this sensible?
113 LDMEQFD R13!,{PC}^ ;No -- return
114
115 STMFD R13!,{R0-R3} ;Save some more registers
116 LDR R14,help__message+0 ;Load the message length
117 ADD R14,R14,#4 ;Word align the size as reqd.
118 BIC R14,R14,#3 ;Yep, indeedy
119 STR R14,help__message+0 ;Store length back again
120
121 ADR R1,help__message ;Point to the message block
122 LDR R2,help__msgTask ;Load the task handle out
123 MOV R0,#0 ;No more messages waiting
124 STR R0,help__msgTask ;So zero the task handle
125 MOV R0,#17 ;Don't care if it bounces
126 SWI Wimp_SendMessage ;Send the message out
127 LDMFD R13!,{R0-R3,PC}^ ;Return to caller
128
129 ; --- Send a finished hint to the hint window ---
130
131 50 STMFD R13!,{R1} ;Save some registers away
132 BIC R14,R14,#hFlag__hinted :OR: hFlag__hinting
133 STR R14,help__flags ;Clear all the hint flags
134 LDR R14,help__window ;Get the hint destination
135 STR R14,[R1,#0] ;Store in the poll block
136 ADD R0,R1,#4 ;Point to next spare field
137 ADR R1,help__message+20 ;Point to hint string
138 BL str_cpy ;Copy it over
139 MOV R0,#-1 ;The magic hint reason code
140 LDMFD R13!,{R1,R14} ;Restore registers
141 ORRS PC,R14,#C_flag ;Return to caller
142
143 ; --- Try to get a new hint from the window ---
144
145 60 STMFD R13!,{R1-R5} ;Save a load of registers
146 ORR R14,R14,#hFlag__hinted ;Dispatch hint next time
147 STR R14,help__flags ;Save new flags word
148
149 ; --- Build a skeleton hint in case of no reply ---
150
151 MOV R0,#0 ;A null string
152 STR R0,help__message+20 ;Store over the string start
153
154 ; --- Build a help request in the poll block ---
155
156 MOV R0,#44 ;Size of help request message
157 MOV R2,#-1 ;A very bogus task handle
158 MOV R3,#-1 ;A similarly bogus my_ref
159 MOV R4,#0 ;This is not a reply
160 MOV R5,#&500 ;Help request message code
161 ORR R5,R5,#&002 ;Finish off message code
162 STMIA R1!,{R0,R2-R5} ;Build message header
163 STR R4,help__msgTask ;Zero destination task handle
164 SWI Wimp_GetPointerInfo ;Get the current pointer pos
165 MOV R0,#18 ;Make it look real!
166 LDMFD R13!,{R1-R5,R14} ;Restore registers
167 ORRS PC,R14,#C_flag ;Return to caller
168
169 LTORG
170
171 ; --- help__postFilter ---
172 ;
173 ; On entry: R0 == event reason code
174 ; R1 == pointer to event block
175 ;
176 ; On exit: --
177 ;
178 ; Use: Catches pointer-entering and pointer-leaving events and
179 ; sets up the idle claimer appropriately.
180
181 help__postFilter ROUT
182
183 ; --- Ensure that we want this event ---
184
185 CMP R0,#4 ;Pointer leaving?
186 MOVNES PC,R14 ;No -- return now
187
188 ; --- Pointer is leaving one of tasks windows ---
189
190 STMFD R13!,{R0-R3,R14} ;Stack some registers
191 LDR R14,help__flags ;Get my flags word
192 TST R14,#hFlag__hintable ;Is window hintable?
193 LDMEQFD R13!,{R0-R3,PC}^ ;No -- ignore this then
194 MOV R0,#5 ;Call it this frequently
195 ADR R1,help__idles ;Call this on idle events
196 MOV R2,#0 ;Our user handle
197 MOV R3,R12 ;Put our workspace in R12
198 BL idle_removeHandler ;Remove handler
199
200 ; --- Pointer has just left the window ---
201 ;
202 ; It looks really silly if the window we left still has a
203 ; hint in it, so we send it a dummy hint with a null string.
204
205 MOV R0,#0 ;A zero byte for the string
206 STR R0,help__message+20 ;Store over the string start
207 LDR R14,help__flags ;Get my flags word
208 ORR R14,R14,#hFlag__hinted ;There's a hint waiting
209 BIC R14,R14,#hFlag__hintable;Disable the hints system
210 STR R14,help__flags ;Store flags back again
211 LDMFD R13!,{R0-R3,PC}^ ;Return to caller
212
213 LTORG
214
215 ; --- help_sendHints ---
216 ;
217 ; On entry: --
218 ;
219 ; On exit: --
220 ;
221 ; Use: Should be called on a pointer-entering-window event. It
222 ; enables hint requests for the window beneath the pointer.
223
224 EXPORT help_sendHints
225 help_sendHints ROUT
226
227 STMFD R13!,{R0-R3,R12,R14} ;Save some registers
228 WSPACE help__wSpace ;Load my workspace address
229 LDR R14,help__flags ;Load my flags word
230 TST R14,#hFlag__hintable ;Are hints enabled?
231 LDMNEFD R13!,{R0-R3,R12,PC}^ ;Yes -- then return now
232 ORR R14,R14,#hFlag__hintable;Set the hints enabled flag
233 STR R14,help__flags ;And save the flags back
234
235 MOV R0,#5 ;Call it this frequently
236 ADR R1,help__idles ;Call this on idle events
237 MOV R2,#0 ;Our user handle
238 MOV R3,R12 ;Put our workspace in R12
239 BL idle_handler ;Add idle handler
240 MOV R0,#-3 ;Set up previous icon hnd
241 STR R0,help__icon ;...to a really weird value
242 LDMFD R13!,{R0-R3,R12,PC}^ ;And return to caller
243
244 LTORG
245
246 ; --- help__idles ---
247 ;
248 ; On entry: --
249 ;
250 ; On exit: --
251 ;
252 ; Use: Catches pointer movement between icons, and sets the hint
253 ; flags accordingly.
254
255 help__idles ROUT
256
257 STMFD R13!,{R0-R2,R14} ;Save some registers away
258 SUB R13,R13,#24 ;Make space for a pointer blk
259 MOV R1,R13 ;Point to it
260 SWI Wimp_GetPointerInfo ;Get the current ptr posn
261 ADD R14,R13,#12 ;Point to window/icon hnds
262 LDMIA R14,{R0,R2} ;Load them out of the block
263 ADD R13,R13,#24 ;Reclaim the stack I used
264
265 ; --- Find out if we need to get a new hint ---
266
267 LDR R1,help__icon ;Get the old icon I was on
268 CMP R1,R2 ;Do they match?
269 BEQ %90help__idles ;Yes -- nothing more to do
270
271 CMP R2,#0 ;Is ptr over the background?
272 MOVLT R2,#-3 ;Yes -- give it a silly value
273 STR R2,help__icon ;No -- store as new old icon
274 STR R0,help__window ;Save the hint window handle
275 LDR R14,help__flags ;Get my flags word
276 ORR R14,R14,#hFlag__hinting ;Get ready to send a hint rq
277 STR R14,help__flags ;Store the flags away again
278
279 90help__idles LDMFD R13!,{R0-R2,PC}^ ;Return to caller
280
281 LTORG
282
283 ; --- help_add ---
284 ;
285 ; On entry: R0 == pointer to message string to add
286 ;
287 ; On exit: --
288 ;
289 ; Use: Adds a line to the help message being built currently. Note
290 ; that overflows are trapped, and errors are generated if one
291 ; would occur.
292
293 EXPORT help_add
294 help_add ROUT
295
296 STMFD R13!,{R0-R4,R12,R14} ;Save some registers
297 WSPACE help__wSpace ;Find my workspace area
298 LDR R14,help__msgTask ;Get the destination task
299 CMP R14,#0 ;Is there one set up?
300 BNE %10help_add ;Yes -- add a subsequent line
301
302 ; --- We're starting a new help reply ---
303
304 BL event_last ;Get the last event out
305 MOV R2,#&500 ;The message code to match
306 ORR R2,R2,#&002 ;Can't load in one op
307 CMP R0,#17 ;Make sure it's a message
308 CMPNE R0,#18 ;Either one will do
309 LDREQ R14,[R1,#16] ;Get the message code
310 CMPEQ R14,R2 ;Does this match up?
311 LDMNEFD R13!,{R0-R4,R12,PC}^ ;If not, return right now
312
313 ; --- Set up the message block ---
314
315 ADD R4,R2,#1 ;The reply code is one larger
316 MOV R0,#20 ;Size of the message block
317 LDR R3,[R1,#8] ;Load his my_ref value
318 MOV R14,#0 ;Null terminate the string
319 STMIB R12,{R0-R4,R14} ;Build the message block
320 LDR R14,[R1,#4] ;Get the task handle out
321 STR R14,help__msgTask ;Store the handle away
322
323 ; --- Set up for main copy loop ---
324
325 LDR R0,[R13,#0] ;Get the string pointer back
326 MOV R1,R11 ;Find a spare buffer
327 BL msgs_build ;Build the message nicely
328 ADR R1,help__message+20 ;Current pointer for string
329 MOV R2,#20 ;Current length
330 B %20help_add ;Now skip to main code
331
332 ; --- Add in a line separator ---
333
334 10help_add MOV R1,R11 ;Find a spare buffer
335 BL msgs_build ;Build the message nicely
336
337 LDR R2,help__message+0 ;Get the current message size
338 ADR R1,help__message ;Point to the message start
339 ADD R1,R1,R2 ;Get current pointer
340 CMP R2,#253 ;Make sure it will fit
341 BGT %90 ;If it doesn't, make error
342
343 LDR R14,help__flags ;Load my flags word
344 TST R14,#hFlag__hinted ;Am I building a hint?
345 MOVEQ R14,#'|' ;No -- strings get GSTransed
346 MOVNE R14,#' ' ;Yes -- spaces not newlines
347 STRB R14,[R1],#1 ;Store the character
348 MOVEQ R14,#'M' ;`|M' is a return character
349 STRB R14,[R1],#1 ;Store the character
350 ADD R2,R2,#2 ;We've added two characters
351
352 ; --- Now copy the string over, trapping overflows ---
353
354 20help_add CMP R2,#256 ;Do we have room for another?
355 BGE %90 ;No -- moan bitterly
356 LDRB R14,[R0],#1 ;Get an input character
357 CMP R14,#' ' ;Is this a control character?
358 MOVLT R14,#0 ;Yes -- store a zero nicely
359 STRB R14,[R1],#1 ;Store it in my message
360 ADD R2,R2,#1 ;Bump the character count
361 BGE %20help_add ;Loop round for more
362
363 ; --- Set things up for next time ---
364
365 SUB R2,R2,#1 ;Overwrite the last null byte
366 STR R2,help__message+0 ;Store the message length
367 LDMFD R13!,{R0-R4,R12,PC}^ ;Return to caller
368
369 ; --- We overflowed -- complain ---
370
371 90help_add MOV R0,#0 ;Zero the task handle...
372 STR R0,help__msgTask ;...to stop it being sent
373 ADR R0,help__overflow ;Point to the message
374 BL msgs_error ;Translate it as normal
375 SWI OS_GenerateError ;And generate the error
376
377 help__overflow DCD 1
378 DCB "helpOFLOW",0
379
380 LTORG
381
382 ; --- help_reset ---
383 ;
384 ; On entry: --
385 ;
386 ; On exit: --
387 ;
388 ; Use: Resets the help system so that a hint request is sent to an
389 ; icon that the pointer is already over. The proposed use
390 ; is that the caller can change a help message for a given
391 ; icon as soon as it is clicked on.
392
393 EXPORT help_reset
394 help_reset ROUT
395
396 STMFD R13!,{R12,R14} ;Stack some registers
397 WSPACE help__wSpace ;Load my workspace address
398 MOV R14,#-3 ;Set up previous icon hnd
399 STR R14,help__icon ;...to a really weird value
400 LDMFD R13!,{R12,PC}^ ;Return to caller
401
402 LTORG
403
404 ;----- Workspace ------------------------------------------------------------
405
406 ^ 0,R12
407 help__wStart # 0
408
409 help__flags # 4 ;Various flags
410 help__message # 256 ;The actual message to send
411 help__msgTask # 4 ;Task to send message to
412 help__msgNext # 4 ;Pointer to message tail
413 help__window # 4 ;The window the ptr is over
414 help__icon # 4 ;The icon the ptr is over
415
416 help__wSize EQU {VAR}-help__wStart
417
418 hFlag__inited EQU (1<<0) ;Am I initialised?
419 hFlag__hintable EQU (1<<1) ;Current window wants hints
420 hFlag__hinting EQU (1<<2) ;We're gathering up a hint
421 hFlag__hinted EQU (1<<3) ;Is a hint waiting?
422
423 AREA |Sapphire$$LibData|,CODE,READONLY
424
425 DCD help__wSize
426 DCD help__wSpace
427 DCD 0
428 DCD help_init
429
430 ;----- That's all, folks ----------------------------------------------------
431
432 END
The Straylight Source Distribution (obsolete software for RISC OS)