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