4 * APCS interface to Sculptrix
6 * © 1997-1998 Straylight
9 /*----- Licensing note ----------------------------------------------------*
11 * This file is part of Straylight's Sculptrix.
13 * Sculptrix 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)
18 * Sculptrix 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.
23 * You should have received a copy of the GNU General Public License
24 * along with Sculptrix. If not, write to the Free Software Foundation,
25 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
31 /*----- Notes -------------------------------------------------------------*
33 * The interfaces to Sculptrix have been written in assembler. This has the
34 * benefit of making them very small and minimising procedure call overhead.
35 * It also has the disadvantage of not setting _kernel_last_oserror()
36 * properly. If this is important, you should use _kernel_swi() directly.
38 * The SWI interface routines are safe to call from SVC mode (e.g. in a
46 /*----- Important types ---------------------------------------------------*/
48 /* --- sculptrix_slabDesc --- *
50 * A Sculptrix slab descriptor.
53 typedef struct sculptrix_slabDesc {
54 unsigned long window; /* Window containing button */
55 unsigned long icon; /* Icon handle of button */
56 unsigned colour; /* Old button colour, and flags */
57 unsigned long time; /* Time of the slab call */
61 scFlag_noButton = 1 << 8 /* Slab wasn't result of mouse */
64 /* --- sculptrix_config --- *
66 * A Sculptrix configuration block.
69 typedef struct sculptrix_config {
70 unsigned flags; /* Flags word (see below) */
71 unsigned char nDark, nLight; /* Normal dark and light colours */
72 unsigned char gDark, gLight; /* Group box dark and light */
73 unsigned char snDark, snLight; /* Shaded dark and light */
74 unsigned char sgDark, sgLight; /* Shaded group dark and light */
75 unsigned char highlight; /* Default button highlight colour */
76 unsigned char slab; /* Slabbed button colour */
77 unsigned char _reserved_a, _reserved_b; /* Two reserved bytes */
78 unsigned long _reserved_c, _reserved_d; /* And two words, for safety */
82 scFlag_acorn = 1 << 0 /* Use nasty Acorn group boxes */
85 /* --- sculptrix_error --- *
87 * This is the type of error which Sculptrix SWIs return. Depending on
88 * whether you're using RISC_OSLib or not, you may want these to return
89 * os_errors or _kernel_oserrors, or its own special type. All these error
90 * structures have the same format and member names -- it's just a matter of
91 * naming the structure.
93 * The way we sort all this out is by allowing the client to set up a macro
94 * to tell us what to do.
97 #if defined(sculptrix_USE_OS_ERROR)
103 typedef os_error sculptrix_error;
105 #elif defined(sculptrix_USE_KERNEL_OSERROR)
111 typedef _kernel_oserror sculptrix_error;
113 #elif !defined(sculptrix_error)
115 typedef struct sculptrix_error
117 int errnum; /* Error number */
118 char errmess[252]; /* Error message text */
124 /*----- Interface functions -----------------------------------------------*/
126 /* --- sculptrix_redrawWindow --- *
128 * Arguments: const void *redraw == pointer to a redraw block
130 * Returns: Pointer to possible error
132 * Use: Redraws the window's borders, in response to a
133 * RedrawWindowRequest event from the Wimp.
135 * Note that the redraw block is passed as a `void *' argument
136 * because the type used to represent a redraw block is
137 * dependent upon the library being used.
140 extern sculptrix_error *sculptrix_redrawWindow(const void */*redraw*/);
142 /* --- sculptrix_doSlab --- *
144 * Arguments: unsigned long w == window handle
145 * unsigned long i == icon handle
146 * unsigned c == colour to set in the icon
147 * unsigned *oc == address to store old colour, or null
149 * Returns: Pointer to possible error
151 * Use: Low-level slabbing operation.
154 extern sculptrix_error *sculptrix_doSlab(unsigned long /*w*/,
159 /* --- sculptrix_slabIcon --- *
161 * Arguments: unsigned long w == window handle
162 * unsigned long i == icon handle
163 * sculptrix_slabDesc *d == pointer to slab descriptor
165 * Returns: Pointer to possible error
167 * Use: Slabs an icon, and stores state information into the
168 * descriptor, suitable for unslabbing later.
171 extern sculptrix_error *sculptrix_slabIcon(unsigned long /*w*/,
173 sculptrix_slabDesc */*d*/);
175 /* --- sculptrix_unslabIcon --- *
177 * Arguments: sculptrix_slabDesc *d == pointer to slab descriptor
179 * Returns: Pointer to possible error
181 * Use: Unslabs an icon, using the state information stored in the
185 extern sculptrix_error *sculptrix_unslabIcon(sculptrix_slabDesc */*d*/);
187 /* --- sculptrix_boundingBox --- *
189 * Arguments: void *i == pointer to an icon block
191 * Returns: Zero if there was no Sculptrix border, or nonzero if there
194 * Use: Reports the presence of a Sculptrix border, and if there was
195 * one, adjusts the bounding box of the icon block passed to
196 * include the border's size.
198 * Note that the icon block is passed as a `void *' argument,
199 * because the type used to represent an icon is dependent on
200 * the library being used.
203 extern int sculptrix_boundingBox(void */*i*/);
205 /* --- sculptrix_plotIcon --- *
207 * Arguments: const void *i == pointer to an icon block
208 * const void *r == pointer to a redraw block
210 * Returns: Pointer to possible error
212 * Use: Plots an icon's border immediately.
214 * Note that the icon and redraw blocks are passed as `void *'
215 * arguments, because the types used to represent these blocks
216 * depend on the library being used.
219 extern sculptrix_error *sculptrix_plotIcon(const void */*i*/,
222 /* --- sculptrix_plotGroup --- *
224 * Arguments: const void *i == pointer to icon block
225 * const void *r == pointer to redraw block
226 * const char *p == pointer to group box title
228 * Returns: Pointer to possible error
230 * Use: Plots a group box border. Arguments of type `void *' used
234 extern sculptrix_error *sculptrix_plotGroup(const void */*i*/,
238 /* --- sculptrix_setSpriteArea --- *
240 * Arguments: const void *s == pointer to sprite area, or null for Wimp
243 * Returns: Pointer to possible error
245 * Use: Sets the sprite area to be used when plotting `xs'-type
246 * icons. Note the deviation from the Sculptrix SWI interface
247 * above -- a null pointer is passed to represent the Wimp pool
248 * instead of the value 1 used by the SWI.
251 extern sculptrix_error *sculptrix_setSpriteArea(const void *s);
253 /* --- sculptrix_updateIcon --- *
255 * Arguments: unsigned long w == window handle
256 * unsigned long i == icon handle
258 * Returns: Pointer to possible error
260 * Use: Updates an icon's border. Call this after modifying the
264 extern sculptrix_error *sculptrix_updateIcon(unsigned long /*w*/,
265 unsigned long /*i*/);
267 /* --- sculptrix_slabColour --- *
271 * Returns: The colour currently used for slabbing icons
273 * Use: Returns the current slab colour. Useful for handling
277 extern unsigned sculptrix_slabColour(void);
279 /* --- sculptrix_setConfig --- *
281 * Arguments: const sculptrix_config *cfg == pointer to configuration block
283 * Returns: Zero if the configuration didn't change, nonzero if it did.
285 * Use: Sets the Sculptrix configuration.
288 extern int sculptrix_setConfig(const sculptrix_config */*cfg*/);
290 /* --- sculptrix_readConfig --- *
292 * Arguments: sculptrix_config *cfg == pointer to configuration buffer
293 * unsigned long sz == size of buffer
295 * Returns: Pointer to possible error
297 * use: Reads the current Sculptrix configuration.
300 extern sculptrix_error *sculptrix_readConfig(sculptrix_config */*cfg*/,
301 unsigned long /*sz*/);
303 /*----- That's all, folks -------------------------------------------------*/