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