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