2ee739cc |
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. * |
6 | * * |
7 | ***************************************************************************/ |
8 | |
9 | /*----- Licensing note ----------------------------------------------------* |
10 | * |
11 | * This file is part of Straylight's Steel library. |
12 | * |
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) |
16 | * any later version. |
17 | * |
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. |
22 | * |
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. |
26 | */ |
27 | |
28 | /* |
29 | * Title : wimpt.h |
30 | * Purpose: provides low-level wimp functionality |
31 | * |
32 | */ |
33 | |
34 | # ifndef __wimpt_h |
35 | # define __wimpt_h |
36 | |
37 | # ifndef __wimp_h |
38 | # include "wimp.h" |
39 | # endif |
40 | |
41 | # ifndef __os_h |
42 | # include "os.h" |
43 | # endif |
44 | |
45 | #ifndef BOOL |
46 | #define BOOL int |
47 | #define TRUE 1 |
48 | #define FALSE 0 |
49 | #endif |
50 | |
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 */ |
57 | |
58 | /* ------------------------------ wimpt_poll ------------------------------- |
59 | * Description: Poll for an event from the wimp (with extras to buffer |
60 | * one event). |
61 | * |
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 |
68 | * shown below. |
69 | * |
70 | */ |
71 | |
72 | os_error * wimpt_poll(wimp_emask mask, wimp_eventstr *result); |
73 | |
74 | /* |
75 | * int wimpt_pollingTime(int new) |
76 | * |
77 | * Use |
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. |
81 | * |
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. |
84 | * |
85 | * Parameters |
86 | * int new == the new setting for the polling time, or -1 to read |
87 | * |
88 | * Returns |
89 | * The setting of the polling time in force when the call was made. |
90 | */ |
91 | |
92 | int wimpt_pollingTime(int new); |
93 | |
94 | /* |
95 | * BOOL wimpt_justChangedMode(void) |
96 | * |
97 | * Use |
98 | * Returns whether we have just changed mode |
99 | */ |
100 | |
101 | BOOL wimpt_justChangedMode(void); |
102 | |
103 | /* -------------------------- wimpt_fake_event ----------------------------- |
104 | * Description: Post an event to be collected by wimpt_poll. |
105 | * |
106 | * Parameters: wimp_eventstr * -- the posted event |
107 | * Returns: void |
108 | * Other Info: use with care! |
109 | * |
110 | */ |
111 | |
112 | void wimpt_fake_event(wimp_eventstr *); |
113 | |
114 | |
115 | /* ----------------------------- wimpt_last_event -------------------------- |
116 | * Description: Informs caller of last event returned by wimpt_poll. |
117 | * |
118 | * Parameters: void |
119 | * Returns: pointer to last event returned by wimpt_poll. |
120 | * Other Info: none. |
121 | * |
122 | */ |
123 | |
124 | wimp_eventstr *wimpt_last_event(void); |
125 | |
126 | |
127 | /* ---------------------- wimpt_last_event_was_a_key ----------------------- |
128 | * Description: Informs caller if last event returned by wimpt_poll was |
129 | * a key stroke. |
130 | * |
131 | * Parameters: void |
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. |
136 | * |
137 | */ |
138 | |
139 | int wimpt_last_event_was_a_key(void); |
140 | |
141 | |
142 | /* ------------------------------ wimpt_noerr ------------------------------ |
143 | * Description: Halts program and reports error in dialogue box (if e!=0). |
144 | * |
145 | * Parameters: os_error *e -- error return from system call |
146 | * Returns: void. |
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". |
153 | * |
154 | */ |
155 | |
156 | void wimpt_noerr(os_error *e); |
157 | |
158 | |
159 | /* ----------------------------- wimpt_complain ---------------------------- |
160 | * Description: Reports error in dialogue box (if e!=0). |
161 | * |
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). |
167 | * |
168 | */ |
169 | |
170 | os_error *wimpt_complain(os_error *e); |
171 | |
172 | |
173 | |
174 | /* -------- Control of graphics environment -------- */ |
175 | |
176 | |
177 | /* -------------------------- wimpt_checkmode ---------------------------- |
178 | * Description: Registers with the wimpt module the current screen |
179 | * mode. |
180 | * |
181 | * Parameters: void |
182 | * Returns: TRUE if screen mode has changed. |
183 | * Other Info: none. |
184 | * |
185 | */ |
186 | |
187 | BOOL wimpt_checkmode(void); |
188 | |
189 | |
190 | /* --------------------------- wimpt_mode -------------------------------- |
191 | * Description: Reads the screen mode |
192 | * |
193 | * Parameters: void |
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. |
197 | * |
198 | */ |
199 | |
200 | int wimpt_mode(void); |
201 | |
202 | |
203 | /* ---------------------- wimpt_dx/wimpt_dy ------------------------------ |
204 | * Description: Inform caller of OS x/y units per screen pixel |
205 | * |
206 | * Parameters: void |
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. |
210 | * |
211 | */ |
212 | |
213 | int wimpt_dx(void); |
214 | int wimpt_dy(void); |
215 | |
216 | |
217 | /* -------------------------- wimpt_bpp ---------------------------------- |
218 | * Description: Informs caller of bits per screen pixel. |
219 | * |
220 | * Parameters: void |
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. |
224 | * |
225 | */ |
226 | |
227 | int wimpt_bpp(void); |
228 | |
229 | int wimpt_scwidth(void); |
230 | int wimpt_scheight(void); |
231 | |
232 | /* |
233 | * void wimpt_setMessages(int msg,...) |
234 | * |
235 | * Use |
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. |
239 | * |
240 | * Parameters |
241 | * A list of message numbers, terminated by 0. |
242 | */ |
243 | |
244 | void wimpt_setMessages(int msg,...); |
245 | |
246 | /* |
247 | * void wimpt_wimpversion(int version) |
248 | * |
249 | * Use |
250 | * Sets up Steel to use a later version of the WIMP than normal. |
251 | * |
252 | * Parameters |
253 | * int version == 100 * the latest version number known about |
254 | */ |
255 | |
256 | void wimpt_wimpversion(int version); |
257 | |
258 | /* --------------------------- wimpt_init -------------------------------- |
259 | * Description: Set program up as a WIMP task. |
260 | * |
261 | * Parameters: char *programname -- name of your program |
262 | * Returns: void |
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. |
275 | * |
276 | */ |
277 | |
278 | void wimpt_init(char *programname); |
279 | |
280 | void wimpt_setOptions(int eor,int bic); |
281 | int wimpt_options(void); |
282 | |
283 | #define wimpt_init_noInterface(name) \ |
284 | do \ |
285 | { \ |
286 | wimpt_setOptions(0,wimpt_OSCULPTRIX | \ |
287 | wimpt_OINTERFACE | \ |
288 | wimpt_OWIMPEXT); \ |
289 | wimpt_init(name); \ |
290 | } \ |
291 | while (0) |
292 | |
293 | #define wimpt_useWimpExt(x) \ |
294 | wimpt_setOptions(wimpt_OWIMPEXT,wimpt_OWIMPEXT); |
295 | |
296 | /* |
297 | * int wimpt_getVersion(void) |
298 | * |
299 | * Use |
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 |
303 | * |
304 | * Returns |
305 | * Version, as above, * 100 |
306 | */ |
307 | |
308 | int wimpt_getVersion(void); |
309 | |
310 | /* |
311 | * BOOL wimpt_interface(void) |
312 | * |
313 | * Use |
314 | * Informs caller if Interface is being used in the application. |
315 | * |
316 | * Returns |
317 | * TRUE if Interface is being used. |
318 | */ |
319 | |
320 | #define wimpt_interface(x) \ |
321 | (wimpt_options() & wimpt_OINTERFACE) |
322 | |
323 | /* ----------------------------- wimpt_programname ----------------------- |
324 | * Description: Informs the caller of name passed to wimpt_init |
325 | * |
326 | * Parameters: void |
327 | * Returns: the program's name (pointer to). |
328 | * Other Info: none. |
329 | * |
330 | */ |
331 | |
332 | char *wimpt_programname(void); |
333 | |
334 | |
335 | /* -------------------------- wimpt_reporterror -------------------------- |
336 | * Description: Reports an OS error in a dialogue box. |
337 | * (including program name) |
338 | * |
339 | * Parameters: os_error* -- OS error block |
340 | * wimp_errflags -- flag whether to include OK and/or |
341 | * CANCEL(highlighted or not) button |
342 | * in dialogue box |
343 | * Returns: void. |
344 | * Other Info: similar to wimp_reporterror(), but includes prog. name |
345 | * automatically (eg. the one passed to wimpt_init). |
346 | * |
347 | */ |
348 | |
349 | void wimpt_reporterror(os_error*, wimp_errflags); |
350 | |
351 | |
352 | /* ----------------------------- wimpt_task ------------------------------ |
353 | * Description: Informs caller of its task handle. |
354 | * |
355 | * Parameters: void |
356 | * Returns: task handle. |
357 | * Other Info: none. |
358 | * |
359 | */ |
360 | |
361 | wimp_t wimpt_task(void); |
362 | |
363 | |
364 | /* ----------------------------- wimpt_forceredraw ----------------------- |
365 | * Description: Causes whole screen to be invalidated (ie. running |
366 | * applications will be requested to redraw all windows) |
367 | * |
368 | * Parameters: void |
369 | * Returns: void. |
370 | * Other Info: none. |
371 | * |
372 | */ |
373 | |
374 | void wimpt_forceredraw(void); |
375 | |
376 | typedef void (*wimpt_redraw_proc)(wimp_redrawstr *r,void *handle); |
377 | void wimpt_redraw(wimpt_redraw_proc rdr,void *handle); |
378 | |
379 | /* |
380 | * int wimpt_stringWidth(char *s) |
381 | * |
382 | * Use |
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. |
385 | * |
386 | * Parameters |
387 | * char *s == pointer to the string to font the length of |
388 | * |
389 | * Returns |
390 | * The width of the string in OS units |
391 | */ |
392 | |
393 | int wimpt_stringWidth(char *s); |
394 | |
395 | #endif |