1 /****************************************************************************
2 * This source file was written by Acorn Computers Limited. It is part of *
3 * the RISCOS library for writing applications in C for RISC OS. It may be *
4 * used freely in the creation of programs for Archimedes. It should be *
5 * used with Acorn's C Compiler Release 3 or later. *
7 ***************************************************************************/
9 /*----- Licensing note ----------------------------------------------------*
11 * This file is part of Straylight's Steel library.
13 * Steel is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2, or (at your option)
18 * Steel is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
23 * You should have received a copy of the GNU General Public License
24 * along with Steel. If not, write to the Free Software Foundation,
25 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
30 * Purpose: provides low-level wimp functionality
51 #define wimpt_OSCULPTRIX (1<<0) /* Support Sculptrix 3D icons */
52 #define wimpt_OINTERFACE (1<<1) /* Support Interface 3D icons */
53 #define wimpt_OWIMPEXT (1<<2) /* Support WimpExtension a bit */
54 #define wimpt_ONOWIMPSHADE (1<<3) /* Use fancy shading in dboxes */
55 #define wimpt_OREMSAVEICON (1<<4) /* Hide save icon in sprite drag */
56 #define wimpt_ONOBACKTRACE (1<<5) /* Don't offer backtrace buttons */
58 /* ------------------------------ wimpt_poll -------------------------------
59 * Description: Poll for an event from the wimp (with extras to buffer
62 * Parameters: wimp_emask mask -- ignore events in the mask
63 * wimp_eventstr *result -- the event returned from wimp
64 * Returns: possible error condition.
65 * Other Info: If you want to poll at this low level (ie avoiding
66 * event_process()), then use this function rather than
67 * wimp_poll. Using wimpt_poll allows you to use the routines
72 os_error * wimpt_poll(wimp_emask mask, wimp_eventstr *result);
75 * int wimpt_pollingTime(int new)
78 * Adjusts the time spent between polls with idle events enabled. The
79 * current polling time may be read by passing new as -1. Otherwise, the
80 * time is set to be new, and the previous setting is returned.
82 * The polling is performed using Wimp_PollIdle, unless the polling time
83 * is set to 0, in which case full scale processor-hog mode is engaged.
86 * int new == the new setting for the polling time, or -1 to read
89 * The setting of the polling time in force when the call was made.
92 int wimpt_pollingTime(int new);
95 * BOOL wimpt_justChangedMode(void)
98 * Returns whether we have just changed mode
101 BOOL wimpt_justChangedMode(void);
103 /* -------------------------- wimpt_fake_event -----------------------------
104 * Description: Post an event to be collected by wimpt_poll.
106 * Parameters: wimp_eventstr * -- the posted event
108 * Other Info: use with care!
112 void wimpt_fake_event(wimp_eventstr *);
115 /* ----------------------------- wimpt_last_event --------------------------
116 * Description: Informs caller of last event returned by wimpt_poll.
119 * Returns: pointer to last event returned by wimpt_poll.
124 wimp_eventstr *wimpt_last_event(void);
127 /* ---------------------- wimpt_last_event_was_a_key -----------------------
128 * Description: Informs caller if last event returned by wimpt_poll was
132 * Returns: non-zero if last event was a keystroke.
133 * Other Info: retained for compatibility with old world.
134 * Use wimpt_last_event by preference, and test
135 * if e field of returned struct == wimp_EKEY.
139 int wimpt_last_event_was_a_key(void);
142 /* ------------------------------ wimpt_noerr ------------------------------
143 * Description: Halts program and reports error in dialogue box (if e!=0).
145 * Parameters: os_error *e -- error return from system call
147 * Other Info: Useful for "wrapping up" system calls which are not
148 * expected to fail; if so your program probably has a
149 * logical error. Call when an error would mean disaster!!
150 * eg. wimpt_noerr(some_system_call(.......));
151 * Error message is : "<ProgName> has suffered a fatal
152 * internal error (<errormessage>) and must exit immediately".
156 void wimpt_noerr(os_error *e);
159 /* ----------------------------- wimpt_complain ----------------------------
160 * Description: Reports error in dialogue box (if e!=0).
162 * Parameters: os_error *e -- error return from system call
163 * Returns: the error returned from the system call (ie. e).
164 * Other Info: Useful for "wrapping up" system calls which may fail. Call
165 * when your program can still limp on regardless (taking
166 * some appropriate action).
170 os_error *wimpt_complain(os_error *e);
174 /* -------- Control of graphics environment -------- */
177 /* -------------------------- wimpt_checkmode ----------------------------
178 * Description: Registers with the wimpt module the current screen
182 * Returns: TRUE if screen mode has changed.
187 BOOL wimpt_checkmode(void);
190 /* --------------------------- wimpt_mode --------------------------------
191 * Description: Reads the screen mode
194 * Returns: screen mode.
195 * Other Info: faster than a normal OS call. Value is only valid if
196 * wimpt_checkmode is called at redraw events.
200 int wimpt_mode(void);
203 /* ---------------------- wimpt_dx/wimpt_dy ------------------------------
204 * Description: Inform caller of OS x/y units per screen pixel
207 * Returns: OS x/y units per screen pixel.
208 * Other Info: faster than a normal OS call. Value is only valid if
209 * wimpt_checkmode is called at redraw events.
217 /* -------------------------- wimpt_bpp ----------------------------------
218 * Description: Informs caller of bits per screen pixel.
221 * Returns: bits per screen pixel (in current mode).
222 * Other Info: faster than a normal OS call. Value is only valid if
223 * wimpt_checkmode is called at redraw events.
229 int wimpt_scwidth(void);
230 int wimpt_scheight(void);
233 * void wimpt_setMessages(int msg,...)
236 * Sets up the messages that the task is to respond to. If ommitted,
237 * suitable defaults are included. Call before wimpt_init. If the WIMP
238 * version is lower than 3.00, 3.00 is specified.
241 * A list of message numbers, terminated by 0.
244 void wimpt_setMessages(int msg,...);
247 * void wimpt_wimpversion(int version)
250 * Sets up Steel to use a later version of the WIMP than normal.
253 * int version == 100 * the latest version number known about
256 void wimpt_wimpversion(int version);
258 /* --------------------------- wimpt_init --------------------------------
259 * Description: Set program up as a WIMP task.
261 * Parameters: char *programname -- name of your program
263 * Other Info: Remembers screen mode, and sets up signal handlers
264 * so that task exits cleanly, even after fatal errors.
265 * Response to signals SIGABRT, SIGFPE, SIGILL, SIGSEGV
266 * SIGTERM is to display error box with message:
267 * "<progname> has suffered an internal error (type =
268 * <signal>) and must exit immediately"
269 * SIGINT (Escape) is ignored. Progname will appear in the
270 * task manager display and in error messages.
271 * Calls wimp_taskinit and stores task_id returned
272 * Also installs exit-handler to close down task when
273 * program calls exit() function. If version has not been
274 * set, it is worked out according to the current OS version.
278 void wimpt_init(char *programname);
280 void wimpt_setOptions(int eor,int bic);
281 int wimpt_options(void);
283 #define wimpt_init_noInterface(name) \
286 wimpt_setOptions(0,wimpt_OSCULPTRIX | \
293 #define wimpt_useWimpExt(x) \
294 wimpt_setOptions(wimpt_OWIMPEXT,wimpt_OWIMPEXT);
297 * int wimpt_getVersion(void)
300 * Before wimpt_init, returns the version the application will be started
301 * with (0 for guess), and afterwards, returns the WIMP version that the
302 * application has been initialised with
305 * Version, as above, * 100
308 int wimpt_getVersion(void);
311 * BOOL wimpt_interface(void)
314 * Informs caller if Interface is being used in the application.
317 * TRUE if Interface is being used.
320 #define wimpt_interface(x) \
321 (wimpt_options() & wimpt_OINTERFACE)
323 /* ----------------------------- wimpt_programname -----------------------
324 * Description: Informs the caller of name passed to wimpt_init
327 * Returns: the program's name (pointer to).
332 char *wimpt_programname(void);
335 /* -------------------------- wimpt_reporterror --------------------------
336 * Description: Reports an OS error in a dialogue box.
337 * (including program name)
339 * Parameters: os_error* -- OS error block
340 * wimp_errflags -- flag whether to include OK and/or
341 * CANCEL(highlighted or not) button
344 * Other Info: similar to wimp_reporterror(), but includes prog. name
345 * automatically (eg. the one passed to wimpt_init).
349 void wimpt_reporterror(os_error*, wimp_errflags);
352 /* ----------------------------- wimpt_task ------------------------------
353 * Description: Informs caller of its task handle.
356 * Returns: task handle.
361 wimp_t wimpt_task(void);
364 /* ----------------------------- wimpt_forceredraw -----------------------
365 * Description: Causes whole screen to be invalidated (ie. running
366 * applications will be requested to redraw all windows)
374 void wimpt_forceredraw(void);
376 typedef void (*wimpt_redraw_proc)(wimp_redrawstr *r,void *handle);
377 void wimpt_redraw(wimpt_redraw_proc rdr,void *handle);
380 * int wimpt_stringWidth(char *s)
383 * Determines the width of a string in OS units, taking into account the
384 * fact that it may be represented in a WIMP anti-aliased font.
387 * char *s == pointer to the string to font the length of
390 * The width of the string in OS units
393 int wimpt_stringWidth(char *s);