Initial revision

[ssr] / StraySrc / Libraries / Steel / h / wimpt

/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the RISCOS library for writing applications in C for RISC OS. It may be  *
 * used freely in the creation of programs for Archimedes. It should be     *
 * used with Acorn's C Compiler Release 3 or later.                         *
 *                                                                          *
 ***************************************************************************/

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel 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.
 *
 * Steel 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 Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*
 * Title  : wimpt.h
 * Purpose: provides low-level wimp functionality
 *
 */

# ifndef __wimpt_h
# define __wimpt_h

# ifndef __wimp_h
# include "wimp.h"
# endif

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

#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif

#define wimpt_OSCULPTRIX	(1<<0)    /* Support Sculptrix 3D icons    */
#define wimpt_OINTERFACE	(1<<1)    /* Support Interface 3D icons    */
#define wimpt_OWIMPEXT		(1<<2)    /* Support WimpExtension a bit   */
#define wimpt_ONOWIMPSHADE	(1<<3)    /* Use fancy shading in dboxes   */
#define wimpt_OREMSAVEICON      (1<<4)    /* Hide save icon in sprite drag */
#define wimpt_ONOBACKTRACE      (1<<5)    /* Don't offer backtrace buttons */

/* ------------------------------ wimpt_poll -------------------------------
 * Description:   Poll for an event from the wimp (with extras to buffer
 *                one event).
 *
 * Parameters:    wimp_emask mask -- ignore events in the mask
 *                wimp_eventstr *result -- the event returned from wimp
 * Returns:       possible error condition.
 * Other Info:    If you want to poll at this low level (ie avoiding
 *                event_process()), then use this function rather than
 *                wimp_poll. Using wimpt_poll allows you to use the routines
 *                shown below.
 *
 */

os_error * wimpt_poll(wimp_emask mask, wimp_eventstr *result);

/*
 * int wimpt_pollingTime(int new)
 *
 * Use
 *  Adjusts the time spent between polls with idle events enabled.  The
 *  current polling time may be read by passing new as -1.  Otherwise, the
 *  time is set to be new, and the previous setting is returned.
 *
 *  The polling is performed using Wimp_PollIdle, unless the polling time
 *  is set to 0, in which case full scale processor-hog mode is engaged.
 *
 * Parameters
 *  int new == the new setting for the polling time, or -1 to read
 *
 * Returns
 *  The setting of the polling time in force when the call was made.
 */

int wimpt_pollingTime(int new);

/*
 * BOOL wimpt_justChangedMode(void)
 *
 * Use
 *  Returns whether we have just changed mode
 */

BOOL wimpt_justChangedMode(void);

/* -------------------------- wimpt_fake_event -----------------------------
 * Description:   Post an event to be collected by wimpt_poll.
 *
 * Parameters:    wimp_eventstr * -- the posted event
 * Returns:       void
 * Other Info:    use with care!
 *
 */

void wimpt_fake_event(wimp_eventstr *);


/* ----------------------------- wimpt_last_event --------------------------
 * Description:   Informs caller of last event returned by wimpt_poll.
 *
 * Parameters:    void
 * Returns:       pointer to last event returned by wimpt_poll.
 * Other Info:    none.
 *
 */

wimp_eventstr *wimpt_last_event(void);


/* ---------------------- wimpt_last_event_was_a_key -----------------------
 * Description:   Informs caller if last event returned by wimpt_poll was
 *                a key stroke.
 *
 * Parameters:    void
 * Returns:       non-zero if last event was a keystroke.
 * Other Info:    retained for compatibility with old world.
 *                Use wimpt_last_event by preference, and test
 *                if e field of returned struct == wimp_EKEY.
 *
 */

int wimpt_last_event_was_a_key(void);


/* ------------------------------ wimpt_noerr ------------------------------
 * Description:   Halts program and reports error in dialogue box (if e!=0).
 *
 * Parameters:    os_error *e -- error return from system call
 * Returns:       void.
 * Other Info:    Useful for "wrapping up" system calls which are not
 *                expected to fail; if so your program probably has a
 *                logical error. Call when an error would mean disaster!!
 *                    eg. wimpt_noerr(some_system_call(.......));
 *                Error message is : "<ProgName> has suffered a fatal
 *                internal error (<errormessage>) and must exit immediately".
 *
 */

void wimpt_noerr(os_error *e);


/* ----------------------------- wimpt_complain ----------------------------
 * Description:   Reports error in dialogue box (if e!=0).
 *
 * Parameters:    os_error *e -- error return from system call
 * Returns:       the error returned from the system call (ie. e).
 * Other Info:    Useful for "wrapping up" system calls which may fail. Call
 *                when your program can still limp on regardless (taking
 *                some appropriate action).
 *
 */

os_error *wimpt_complain(os_error *e);



/* -------- Control of graphics environment -------- */


/* -------------------------- wimpt_checkmode ----------------------------
 * Description:   Registers with the wimpt module the current screen
 *                mode.
 *
 * Parameters:    void
 * Returns:       TRUE if screen mode has changed.
 * Other Info:    none.
 *
 */

BOOL wimpt_checkmode(void);


/* --------------------------- wimpt_mode --------------------------------
 * Description:   Reads the screen mode
 *
 * Parameters:    void
 * Returns:       screen mode.
 * Other Info:    faster than a normal OS call. Value is only valid if
 *                wimpt_checkmode is called at redraw events.
 *
 */

int wimpt_mode(void);


/* ---------------------- wimpt_dx/wimpt_dy ------------------------------
 * Description:   Inform caller of OS x/y units per screen pixel
 *
 * Parameters:    void
 * Returns:       OS x/y units per screen pixel.
 * Other Info:    faster than a normal OS call. Value is only valid if
 *                wimpt_checkmode is called at redraw events.
 *
 */

int wimpt_dx(void);
int wimpt_dy(void);


/* -------------------------- wimpt_bpp ----------------------------------
 * Description:   Informs caller of bits per screen pixel.
 *
 * Parameters:    void
 * Returns:       bits per screen pixel (in current mode).
 * Other Info:    faster than a normal OS call. Value is only valid if
 *                wimpt_checkmode is called at redraw events.
 *
 */

int wimpt_bpp(void);

int wimpt_scwidth(void);
int wimpt_scheight(void);

/*
 * void wimpt_setMessages(int msg,...)
 *
 * Use
 *  Sets up the messages that the task is to respond to.  If ommitted,
 *  suitable defaults are included.  Call before wimpt_init.  If the WIMP
 *  version is lower than 3.00, 3.00 is specified.
 *
 * Parameters
 *  A list of message numbers, terminated by 0.
 */

void wimpt_setMessages(int msg,...);

/*
 * void wimpt_wimpversion(int version)
 *
 * Use
 *  Sets up Steel to use a later version of the WIMP than normal.
 *
 * Parameters
 *  int version == 100 * the latest version number known about
 */

void wimpt_wimpversion(int version);

/* --------------------------- wimpt_init --------------------------------
 * Description:   Set program up as a WIMP task.
 *
 * Parameters:    char *programname -- name of your program
 * Returns:       void
 * Other Info:    Remembers screen mode, and sets up signal handlers
 *                so that task exits cleanly, even after fatal errors.
 *                Response to signals SIGABRT, SIGFPE, SIGILL, SIGSEGV
 *                SIGTERM is to display error box with message:
 *                "<progname> has suffered an internal error (type =
 *                <signal>) and must exit immediately"
 *                SIGINT (Escape) is ignored. Progname will appear in the
 *                task manager display and in error messages.
 *                Calls wimp_taskinit and stores task_id returned
 *                Also installs exit-handler to close down task when
 *                program calls exit() function.  If version has not been
 *                set, it is worked out according to the current OS version.
 *
 */

void wimpt_init(char *programname);

void wimpt_setOptions(int eor,int bic);
int wimpt_options(void);

#define wimpt_init_noInterface(name) \
  do \
  { \
    wimpt_setOptions(0,wimpt_OSCULPTRIX | \
                       wimpt_OINTERFACE | \
                       wimpt_OWIMPEXT); \
    wimpt_init(name); \
  } \
  while (0)

#define wimpt_useWimpExt(x) \
  wimpt_setOptions(wimpt_OWIMPEXT,wimpt_OWIMPEXT);

/*
 * int wimpt_getVersion(void)
 *
 * Use
 *  Before wimpt_init, returns the version the application will be started
 *  with (0 for guess), and afterwards, returns the WIMP version that the
 *  application has been initialised with
 *
 * Returns
 *  Version, as above, * 100
 */

int wimpt_getVersion(void);

/*
 * BOOL wimpt_interface(void)
 *
 * Use
 *  Informs caller if Interface is being used in the application.
 *
 * Returns
 *  TRUE if Interface is being used.
 */

#define wimpt_interface(x) \
  (wimpt_options() & wimpt_OINTERFACE)

/* ----------------------------- wimpt_programname -----------------------
 * Description:   Informs the caller of name passed to wimpt_init
 *
 * Parameters:    void
 * Returns:       the program's name (pointer to).
 * Other Info:    none.
 *
 */

char *wimpt_programname(void);


/* -------------------------- wimpt_reporterror --------------------------
 * Description:   Reports an OS error in a dialogue box.
 *                (including program name)
 *
 * Parameters:    os_error* -- OS error block
 *                wimp_errflags -- flag whether to include OK and/or
 *                                 CANCEL(highlighted or not) button
 *                                 in dialogue box
 * Returns:       void.
 * Other Info:    similar to wimp_reporterror(), but includes prog. name
 *                automatically (eg. the one passed to wimpt_init).
 *
 */

void wimpt_reporterror(os_error*, wimp_errflags);


/* ----------------------------- wimpt_task ------------------------------
 * Description:   Informs caller of its task handle.
 *
 * Parameters:    void
 * Returns:       task handle.
 * Other Info:    none.
 *
 */

wimp_t wimpt_task(void);


/* ----------------------------- wimpt_forceredraw -----------------------
 * Description:   Causes whole screen to be invalidated (ie. running
 *                applications will be requested to redraw all windows)
 *
 * Parameters:    void
 * Returns:       void.
 * Other Info:    none.
 *
 */

void wimpt_forceredraw(void);

typedef void (*wimpt_redraw_proc)(wimp_redrawstr *r,void *handle);
void wimpt_redraw(wimpt_redraw_proc rdr,void *handle);

/*
 * int wimpt_stringWidth(char *s)
 *
 * Use
 *  Determines the width of a string in OS units, taking into account the
 *  fact that it may be represented in a WIMP anti-aliased font.
 *
 * Parameters
 *  char *s == pointer to the string to font the length of
 *
 * Returns
 *  The width of the string in OS units
 */

int wimpt_stringWidth(char *s);

#endif