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

(* ------------------------------ 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. 
 *
 *)
procedure wimpt_poll(mask : wimp_emask;
                result : wimp_eventstr_ptr) : os_error; extern;


(* -------------------------- 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!
 *
 *)
procedure wimpt_fake_event(event : wimp_eventstr_ptr); extern;


(* ----------------------------- 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.
 *
 *)
function wimpt_last_event : wimp_eventstr_ptr; extern;


(* ---------------------- 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.
 *
 *)
function wimpt_last_event_was_a_key : integer; extern;


(* ------------------------------ 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".
 *
 *)
procedure wimpt_noerr(e : os_error); extern;


(* ----------------------------- 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).
 *
 *)
procedure wimpt_complain(e : os_error) : os_error; extern;



(* -------- 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.
 *
 *)
procedure wimpt_checkmode : boolean; extern;


(* --------------------------- 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.
 *
 *)
function wimpt_mode : integer; extern;


(* ---------------------- 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.
 *
 *)
function wimpt_dx : integer; extern;
function wimpt_dy : integer; extern; 


(* -------------------------- 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.
 *
 *)
function wimpt_bpp : integer; extern;


(* --------------------------- 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.
 *
 *)
procedure wimpt_init(programname : string) : integer; extern;                


(* --------------------------- 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.
 *
 *)
procedure wimpt_wimpversion(version : integer); extern;


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


(* -------------------------- 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).
 *
 *)
procedure wimpt_reporterror(e : os_error; flags : wimp_errflags); extern;


(* ----------------------------- wimpt_task ------------------------------
 * Description:   Informs caller of its task handle.
 *
 * Parameters:    void
 * Returns:       task handle.
 * Other Info:    none.
 *
 *)
function wimpt_task : wimp_t; extern;


(* ----------------------------- 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.
 *
 *)
procedure wimpt_forceredraw; extern;

#endif

(* end wimpt.h *)
