/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the "cwimp" 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 2 or later.                         *
 *                                                                          *
 * No support can be given to programmers using this code and, while we     *
 * believe that it is correct, no correspondence can be entered into        *
 * concerning behaviour or bugs.                                            *
 *                                                                          *
 * Upgrades of this code may or may not appear, and while every effort will *
 * be made to keep such upgrades upwards compatible, no guarantees can be   *
 * given.                                                                   *
 ***************************************************************************/

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

os_error * wimpt_poll(wimp_emask mask, wimp_eventstr *result);
/* Identical to wimp_poll, except that the extra facilities below
are provided. All other parts of the program should use wimpt_poll
rather than wimp_poll. */

void wimpt_fake_event(wimp_eventstr *);
/* The wimp_eventstr is saved away, and will be yielded by the next call to
wimpt_poll, rather than calling wimp_poll. If the next call to Poll will not
allow it because of the mask then the fake is discarded. Multiple calls
without wimpt_poll calls will be ignored. */

wimp_eventstr *wimpt_last_event(void);
/* The last value yielded by wimpt_poll. */

int wimpt_last_event_was_a_key(void);
/* replaced by wimpt_last_event: there for compatibility with old world.
   Use wimpt_last_event by preference */

void wimpt_noerr(os_error *e);
/* If e != 0 then wimp_reporterror(e); stop. This is useful for wrapping up
calls to system calls which are not expected to fail. The error message
has "Unexpected system error:" added. This should only arise from logical
errors in the program. */

os_error *wimpt_complain(os_error *e);
/* If e != 0 then wimp_reporterror(e); return e. This is useful for wrapping
up calls to system functions. */

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

void wimpt_setmode(int);
/* Not recommended in the multi-tasking world. */

BOOL wimpt_checkmode(void);
/* Returns TRUE if the mode has changed. */

int wimpt_mode(void); /* read screen mode */
int wimpt_dx(void);   /* OS x units per screen pixel */
int wimpt_dy(void);   /* OS y units per screen pixel */
int wimpt_bpp(void);  /* bits per screen pixel */
/* These calls are fast, backed by variables rather than doing
system enquiry calls. Checkmode must be called at redraw events,
if you use these values. */

void wimpt_init(char *programname);
/* sets up the screen and calls wimp_inittask. Program closedown code
is set up to tidy things up on exit. The program name will appear in
error messages and on the task control panel. */

char *wimpt_programname(void);
void wimpt_reporterror(os_error*, wimp_errflags);
/* Like wimp_reporterror, but fills in the program name. */

wimp_t wimpt_task(void);
/* Gives our task handle. */

void wimpt_forceredraw(void);
/* Invalidate the whole screen. */

/* end h.wimpt */
