wimpt

/* Copyright 1996 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * 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.                         *
 *                                                                          *
 ***************************************************************************/

/*
 * 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


/* ------------------------------ 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);


/* -------------------------- 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);

/* ------------------- wimpt_install_signal_handlers ---------------------
 * Description:   Set up signal handlers to handler unexpected errors
 */
void wimpt_install_signal_handlers(void);

/* --------------------------- wimpt_init --------------------------------
 * Description:   Set program up as a WIMP task.
 *
 * Parameters:    char *programname -- name of your program
 * Returns:       int -- the current wimp version number.
 * 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.
 *
 */

int wimpt_init(char *programname);


/* --------------------------- wimpt_wimpversion --------------------------------
 * Description:   Tell wimpt what version of the wimp you understand.
 *
 * Parameters:    int -- the version number of the wimp that you understand.
 * Returns:       void.
 * Other Info:    Call this routine before calling wimpt_init, if you
 *                know about the features in a Wimp beyond version 2.00.
 *                This argument will then be passed to wimp_init, allowing
 *                the Wimp to understand what facilities you know about.
 *                Then call wimpt_init, allowing the wimp to return
 *                its current version number.
 *
 */

void wimpt_wimpversion(int version);


/* --------------------------- wimpt_messages ------------------------------
 * Description:   Tell wimpt which WIMP messages you understand.
 *
 * Parameters:    action, ... - a list of message numbers, terminated by
 *                wimp_MCLOSEDOWN (which every task must respond to).
 *
 * Returns:       void.
 *
 * Other Info:    Call this routine before calling wimpt_init, if you
 *                know about the message-masking feature of the WIMP
 *                present in version 3.00+. This list will be passed to
 *                SWI Wimp_Initialise. If you call this function without
 *                calling wimpt_version(), wimpt_init() will assume you
 *                know about WIMP 3.00.
 */

void wimpt_messages (wimp_msgaction *messages);

/* ----------------------------- 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);

#endif

/* end wimpt.h */