/*
 * sculptrix.h
 *
 * APCS interface to Sculptrix
 *
 * © 1997-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Sculptrix.
 *
 * Sculptrix is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Sculptrix is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Sculptrix.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __sculptrix_h
#define __sculptrix_h

/*----- Notes -------------------------------------------------------------*
 *
 * The interfaces to Sculptrix have been written in assembler.  This has the
 * benefit of making them very small and minimising procedure call overhead.
 * It also has the disadvantage of not setting _kernel_last_oserror()
 * properly.  If this is important, you should use _kernel_swi() directly.
 *
 * The SWI interface routines are safe to call from SVC mode (e.g. in a
 * C module).
 */

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Important types ---------------------------------------------------*/

/* --- sculptrix_slabDesc --- *
 *
 * A Sculptrix slab descriptor.
 */

typedef struct sculptrix_slabDesc {
  unsigned long window;                 /* Window containing button */
  unsigned long icon;                   /* Icon handle of button */
  unsigned colour;                      /* Old button colour, and flags */
  unsigned long time;                   /* Time of the slab call */
} sculptrix_slabDesc;

enum {
  scFlag_noButton = 1 << 8              /* Slab wasn't result of mouse */
};

/* --- sculptrix_config --- *
 *
 * A Sculptrix configuration block.
 */

typedef struct sculptrix_config {
  unsigned flags;                       /* Flags word (see below) */
  unsigned char nDark, nLight;          /* Normal dark and light colours */
  unsigned char gDark, gLight;          /* Group box dark and light */
  unsigned char snDark, snLight;        /* Shaded dark and light */
  unsigned char sgDark, sgLight;        /* Shaded group dark and light */
  unsigned char highlight;              /* Default button highlight colour */
  unsigned char slab;                   /* Slabbed button colour */
  unsigned char _reserved_a, _reserved_b; /* Two reserved bytes */
  unsigned long _reserved_c, _reserved_d; /* And two words, for safety */
} sculptrix_config;

enum {
  scFlag_acorn = 1 << 0                 /* Use nasty Acorn group boxes */
};

/* --- sculptrix_error --- *
 *
 * This is the type of error which Sculptrix SWIs return.  Depending on
 * whether you're using RISC_OSLib or not, you may want these to return
 * os_errors or _kernel_oserrors, or its own special type.  All these error
 * structures have the same format and member names -- it's just a matter of
 * naming the structure.
 *
 * The way we sort all this out is by allowing the client to set up a macro
 * to tell us what to do.
 */

#if defined(sculptrix_USE_OS_ERROR)

  #ifndef __os_h
    #include "os.h"
  #endif

  typedef os_error sculptrix_error;

#elif defined(sculptrix_USE_KERNEL_OSERROR)

  #ifndef __kernel_h
    #include "kernel.h"
  #endif

  typedef _kernel_oserror sculptrix_error;

#elif !defined(sculptrix_error)

  typedef struct sculptrix_error
  {
    int errnum;                         /* Error number */
    char errmess[252];                  /* Error message text */
  }
  sculptrix_error;

#endif

/*----- Interface functions -----------------------------------------------*/

/* --- sculptrix_redrawWindow --- *
 *
 * Arguments:	const void *redraw == pointer to a redraw block
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Redraws the window's borders, in response to a
 *		RedrawWindowRequest event from the Wimp.
 *
 *		Note that the redraw block is passed as a `void *' argument
 *		because the type used to represent a redraw block is
 *		dependent upon the library being used.
 */

extern sculptrix_error *sculptrix_redrawWindow(const void */*redraw*/);

/* --- sculptrix_doSlab --- *
 *
 * Arguments:	unsigned long w == window handle
 *		unsigned long i == icon handle
 *		unsigned c == colour to set in the icon
 *		unsigned *oc == address to store old colour, or null
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Low-level slabbing operation.
 */

extern sculptrix_error *sculptrix_doSlab(unsigned long /*w*/,
                                         unsigned long /*i*/,
                                         unsigned /*c*/,
                                         unsigned */*oc*/);

/* --- sculptrix_slabIcon --- *
 *
 * Arguments:	unsigned long w == window handle
 *		unsigned long i == icon handle
 *		sculptrix_slabDesc *d == pointer to slab descriptor
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Slabs an icon, and stores state information into the
 *		descriptor, suitable for unslabbing later.
 */

extern sculptrix_error *sculptrix_slabIcon(unsigned long /*w*/,
                                           unsigned long /*i*/,
                                           sculptrix_slabDesc */*d*/);

/* --- sculptrix_unslabIcon --- *
 *
 * Arguments:	sculptrix_slabDesc *d == pointer to slab descriptor
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Unslabs an icon, using the state information stored in the
 *		descriptor.
 */

extern sculptrix_error *sculptrix_unslabIcon(sculptrix_slabDesc */*d*/);

/* --- sculptrix_boundingBox --- *
 *
 * Arguments:	void *i == pointer to an icon block
 *
 * Returns:	Zero if there was no Sculptrix border, or nonzero if there
 *		was one.
 *
 * Use:		Reports the presence of a Sculptrix border, and if there was
 *		one, adjusts the bounding box of the icon block passed to
 *		include the border's size.
 *
 *		Note that the icon block is passed as a `void *' argument,
 *		because the type used to represent an icon is dependent on
 *		the library being used.
 */

extern int sculptrix_boundingBox(void */*i*/);

/* --- sculptrix_plotIcon --- *
 *
 * Arguments:	const void *i == pointer to an icon block
 *		const void *r == pointer to a redraw block
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Plots an icon's border immediately.
 *
 *		Note that the icon and redraw blocks are passed as `void *'
 *		arguments, because the types used to represent these blocks
 *		depend on the library being used.
 */

extern sculptrix_error *sculptrix_plotIcon(const void */*i*/,
                                           const void */*r*/);

/* --- sculptrix_plotGroup --- *
 *
 * Arguments:	const void *i == pointer to icon block
 *		const void *r == pointer to redraw block
 *		const char *p == pointer to group box title
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Plots a group box border.  Arguments of type `void *' used
 *		again.
 */

extern sculptrix_error *sculptrix_plotGroup(const void */*i*/,
                                            const void */*r*/,
                                            const char */*p*/);

/* --- sculptrix_setSpriteArea --- *
 *
 * Arguments:	const void *s == pointer to sprite area, or null for Wimp
 *			area
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Sets the sprite area to be used when plotting `xs'-type
 *		icons.  Note the deviation from the Sculptrix SWI interface
 *		above -- a null pointer is passed to represent the Wimp pool
 *		instead of the value 1 used by the SWI.
 */

extern sculptrix_error *sculptrix_setSpriteArea(const void *s);

/* --- sculptrix_updateIcon --- *
 *
 * Arguments:	unsigned long w == window handle
 *		unsigned long i == icon handle
 *
 * Returns:	Pointer to possible error
 *
 * Use:		Updates an icon's border.  Call this after modifying the
 *		icon's shaded bit.
 */

extern sculptrix_error *sculptrix_updateIcon(unsigned long /*w*/,
                                             unsigned long /*i*/);

/* --- sculptrix_slabColour --- *
 *
 * Arguments:	--
 *
 * Returns:	The colour currently used for slabbing icons
 *
 * Use:		Returns the current slab colour.  Useful for handling
 *		slabbing by hand.
 */

extern unsigned sculptrix_slabColour(void);

/* --- sculptrix_setConfig --- *
 *
 * Arguments:	const sculptrix_config *cfg == pointer to configuration block
 *
 * Returns:	Zero if the configuration didn't change, nonzero if it did.
 *
 * Use:		Sets the Sculptrix configuration.
 */

extern int sculptrix_setConfig(const sculptrix_config */*cfg*/);

/* --- sculptrix_readConfig --- *
 *
 * Arguments:	sculptrix_config *cfg == pointer to configuration buffer
 *		unsigned long sz == size of buffer
 *
 * Returns:	Pointer to possible error
 *
 * use:		Reads the current Sculptrix configuration.
 */

extern sculptrix_error *sculptrix_readConfig(sculptrix_config */*cfg*/,
                                             unsigned long /*sz*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif