chiark - git - mdw - ssr/blob - StraySrc/Sculptrix/apcs/h/sculptrix

   1 /*
   2  * sculptrix.h
   3  *
   4  * APCS interface to Sculptrix
   5  *
   6  * © 1997-1998 Straylight
   7  */
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Sculptrix.
  12  *
  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)
  16  * any later version.
  17  *
  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.
  22  *
  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.
  26  */
  27
  28 #ifndef __sculptrix_h
  29 #define __sculptrix_h
  30
  31 /*----- Notes -------------------------------------------------------------*
  32  *
  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.
  37  *
  38  * The SWI interface routines are safe to call from SVC mode (e.g. in a
  39  * C module).
  40  */
  41
  42 #ifdef __cplusplus
  43   extern "C" {
  44 #endif
  45
  46 /*----- Important types ---------------------------------------------------*/
  47
  48 /* --- sculptrix_slabDesc --- *
  49  *
  50  * A Sculptrix slab descriptor.
  51  */
  52
  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 */
  58 } sculptrix_slabDesc;
  59
  60 enum {
  61   scFlag_noButton = 1 << 8              /* Slab wasn't result of mouse */
  62 };
  63
  64 /* --- sculptrix_config --- *
  65  *
  66  * A Sculptrix configuration block.
  67  */
  68
  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 */
  79 } sculptrix_config;
  80
  81 enum {
  82   scFlag_acorn = 1 << 0                 /* Use nasty Acorn group boxes */
  83 };
  84
  85 /* --- sculptrix_error --- *
  86  *
  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.
  92  *
  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.
  95  */
  96
  97 #if defined(sculptrix_USE_OS_ERROR)
  98
  99   #ifndef __os_h
 100     #include "os.h"
 101   #endif
 102
 103   typedef os_error sculptrix_error;
 104
 105 #elif defined(sculptrix_USE_KERNEL_OSERROR)
 106
 107   #ifndef __kernel_h
 108     #include "kernel.h"
 109   #endif
 110
 111   typedef _kernel_oserror sculptrix_error;
 112
 113 #elif !defined(sculptrix_error)
 114
 115   typedef struct sculptrix_error
 116   {
 117     int errnum;                         /* Error number */
 118     char errmess[252];                  /* Error message text */
 119   }
 120   sculptrix_error;
 121
 122 #endif
 123
 124 /*----- Interface functions -----------------------------------------------*/
 125
 126 /* --- sculptrix_redrawWindow --- *
 127  *
 128  * Arguments:   const void *redraw == pointer to a redraw block
 129  *
 130  * Returns:     Pointer to possible error
 131  *
 132  * Use:         Redraws the window's borders, in response to a
 133  *              RedrawWindowRequest event from the Wimp.
 134  *
 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.
 138  */
 139
 140 extern sculptrix_error *sculptrix_redrawWindow(const void */*redraw*/);
 141
 142 /* --- sculptrix_doSlab --- *
 143  *
 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
 148  *
 149  * Returns:     Pointer to possible error
 150  *
 151  * Use:         Low-level slabbing operation.
 152  */
 153
 154 extern sculptrix_error *sculptrix_doSlab(unsigned long /*w*/,
 155                                          unsigned long /*i*/,
 156                                          unsigned /*c*/,
 157                                          unsigned */*oc*/);
 158
 159 /* --- sculptrix_slabIcon --- *
 160  *
 161  * Arguments:   unsigned long w == window handle
 162  *              unsigned long i == icon handle
 163  *              sculptrix_slabDesc *d == pointer to slab descriptor
 164  *
 165  * Returns:     Pointer to possible error
 166  *
 167  * Use:         Slabs an icon, and stores state information into the
 168  *              descriptor, suitable for unslabbing later.
 169  */
 170
 171 extern sculptrix_error *sculptrix_slabIcon(unsigned long /*w*/,
 172                                            unsigned long /*i*/,
 173                                            sculptrix_slabDesc */*d*/);
 174
 175 /* --- sculptrix_unslabIcon --- *
 176  *
 177  * Arguments:   sculptrix_slabDesc *d == pointer to slab descriptor
 178  *
 179  * Returns:     Pointer to possible error
 180  *
 181  * Use:         Unslabs an icon, using the state information stored in the
 182  *              descriptor.
 183  */
 184
 185 extern sculptrix_error *sculptrix_unslabIcon(sculptrix_slabDesc */*d*/);
 186
 187 /* --- sculptrix_boundingBox --- *
 188  *
 189  * Arguments:   void *i == pointer to an icon block
 190  *
 191  * Returns:     Zero if there was no Sculptrix border, or nonzero if there
 192  *              was one.
 193  *
 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.
 197  *
 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.
 201  */
 202
 203 extern int sculptrix_boundingBox(void */*i*/);
 204
 205 /* --- sculptrix_plotIcon --- *
 206  *
 207  * Arguments:   const void *i == pointer to an icon block
 208  *              const void *r == pointer to a redraw block
 209  *
 210  * Returns:     Pointer to possible error
 211  *
 212  * Use:         Plots an icon's border immediately.
 213  *
 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.
 217  */
 218
 219 extern sculptrix_error *sculptrix_plotIcon(const void */*i*/,
 220                                            const void */*r*/);
 221
 222 /* --- sculptrix_plotGroup --- *
 223  *
 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
 227  *
 228  * Returns:     Pointer to possible error
 229  *
 230  * Use:         Plots a group box border.  Arguments of type `void *' used
 231  *              again.
 232  */
 233
 234 extern sculptrix_error *sculptrix_plotGroup(const void */*i*/,
 235                                             const void */*r*/,
 236                                             const char */*p*/);
 237
 238 /* --- sculptrix_setSpriteArea --- *
 239  *
 240  * Arguments:   const void *s == pointer to sprite area, or null for Wimp
 241  *                      area
 242  *
 243  * Returns:     Pointer to possible error
 244  *
 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.
 249  */
 250
 251 extern sculptrix_error *sculptrix_setSpriteArea(const void *s);
 252
 253 /* --- sculptrix_updateIcon --- *
 254  *
 255  * Arguments:   unsigned long w == window handle
 256  *              unsigned long i == icon handle
 257  *
 258  * Returns:     Pointer to possible error
 259  *
 260  * Use:         Updates an icon's border.  Call this after modifying the
 261  *              icon's shaded bit.
 262  */
 263
 264 extern sculptrix_error *sculptrix_updateIcon(unsigned long /*w*/,
 265                                              unsigned long /*i*/);
 266
 267 /* --- sculptrix_slabColour --- *
 268  *
 269  * Arguments:   --
 270  *
 271  * Returns:     The colour currently used for slabbing icons
 272  *
 273  * Use:         Returns the current slab colour.  Useful for handling
 274  *              slabbing by hand.
 275  */
 276
 277 extern unsigned sculptrix_slabColour(void);
 278
 279 /* --- sculptrix_setConfig --- *
 280  *
 281  * Arguments:   const sculptrix_config *cfg == pointer to configuration block
 282  *
 283  * Returns:     Zero if the configuration didn't change, nonzero if it did.
 284  *
 285  * Use:         Sets the Sculptrix configuration.
 286  */
 287
 288 extern int sculptrix_setConfig(const sculptrix_config */*cfg*/);
 289
 290 /* --- sculptrix_readConfig --- *
 291  *
 292  * Arguments:   sculptrix_config *cfg == pointer to configuration buffer
 293  *              unsigned long sz == size of buffer
 294  *
 295  * Returns:     Pointer to possible error
 296  *
 297  * use:         Reads the current Sculptrix configuration.
 298  */
 299
 300 extern sculptrix_error *sculptrix_readConfig(sculptrix_config */*cfg*/,
 301                                              unsigned long /*sz*/);
 302
 303 /*----- That's all, folks -------------------------------------------------*/
 304
 305 #ifdef __cplusplus
 306   }
 307 #endif
 308
 309 #endif