chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/wimpt

   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