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

   1 /*
   2  * wimpExt.h
   3  *
   4  * C access to DoggySoft's WimpExtension module
   5  *
   6  * © 1993-1998 Straylight
   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 #ifndef __wimpExt_h
  29 #define __wimpExt_h
  30
  31 /*----- Required headers --------------------------------------------------*/
  32
  33 #ifndef __os_h
  34   #include "os.h"
  35 #endif
  36
  37 #ifndef __wimp_h
  38   #include "wimp.h"
  39 #endif
  40
  41 /*----- Data structures and things ----------------------------------------*/
  42
  43 typedef enum wimpExt_features                  /* For wimpExt_initialise   */
  44 {
  45   wimpExt_SEMIAUTOSLAB       =1<<0,
  46   wimpExt_AUTORECREATEMENU   =1<<1,
  47   wimpExt_USEFONTMENUS       =1<<2,
  48   wimpExt_AUTOCOMPACTHEAP    =1<<3,
  49   wimpExt_CORRECTRADIO       =1<<4,
  50   wimpExt_SEMIAUTOHELP       =1<<5,
  51   wimpExt_ALTARGSINSETFLAGS  =1<<6,
  52   wimpExt_MAYBEADDELLIPSIS   =1<<7,
  53   wimpExt_AUTOMOVECARET      =1<<8,
  54   wimpExt_USEESG             =1<<9,
  55   wimpExt_SCROLLONCARETMOVE  =1<<10,
  56   wimpExt_TABDOESNTMOVECARET =1<<11
  57 }
  58 wimpExt_features;
  59
  60 typedef enum wimpExt_ibarSide
  61 {
  62   wimpExt_IBLEFT=-2,
  63   wimpExt_IBRIGHT=-1
  64 }
  65 wimpExt_ibarSide;
  66
  67 typedef enum wimpExt_linkflags
  68 {
  69   wimpExt_CLIPLEFT  =1<<0,
  70   wimpExt_CLIPRIGHT =1<<1,
  71   wimpExt_CLIPABOVE =1<<2,
  72   wimpExt_CLIPBELOW =1<<3,
  73   wimpExt_HIDELINK  =~0x7FFFFFFF /* Yipes */
  74 }
  75 wimpExt_linkflags;
  76
  77 typedef enum wimpExt_templateFlags
  78 {
  79   wimpExt_HCENTRE  =1<<0,
  80   wimpExt_NOCREATE =1<<1,
  81   wimpExt_VCENTRE  =1<<2
  82 }
  83 wimpExt_templateFlags;
  84
  85 typedef enum wimpExt_state
  86 {
  87   wimpExt_RESET,
  88   wimpExt_SET,
  89   wimpExt_TOGGLE
  90 }
  91 wimpExt_state;
  92
  93 #define wimpExt_WIMPAREA ((sprite_area *)1)
  94 #define wimpExt_SYSTEMAREA ((sprite_area *)0)
  95
  96 typedef enum wimpExt_dragFlags
  97 {
  98   /* --- Sprite positionings --- */
  99   wimpExt_HLEFT       =0<<0,
 100   wimpExt_HMID        =1<<0,
 101   wimpExt_HRIGHT      =2<<0,
 102   wimpExt_VBOT        =0<<2,
 103   wimpExt_VMID        =1<<2,
 104   wimpExt_VTOP        =2<<2,
 105
 106   /* --- Mouse bounding box --- */
 107   wimpExt_SCREEN      =0<<4,
 108   wimpExt_WINDOW      =1<<4,
 109   wimpExt_GIVEN       =2<<4,
 110
 111   /* --- Other things --- */
 112   wimpExt_BOUNDSPRITE =1<<6,
 113   wimpExt_SHADOW      =1<<7,
 114   wimpExt_FORCESPRITE =1<<8
 115 }
 116
 117 #define wimpExt_REQUESTER (-3)
 118
 119 #define wimpExt_STANDARDHELP ((void *)1)
 120 #define wimpExt_NOCHANGEHEAP ((void *)-1)
 121 #define wimpExt_NOHEAP((void *)0)
 122
 123 typedef struct wimpExt_heapDescription
 124 {
 125   void *currHeap;
 126   int largestBlock;
 127   int totFree;
 128   int heapUsed;
 129   int totAnchors;
 130   int anchorsUsed;
 131 }
 132 wimpExt_heapDescription;
 133
 134 typedef void *wimpExt_heapAnchor;
 135
 136 /*----- Routines ----------------------------------------------------------*
 137  *
 138  * These aren't described in great detail here.  Instead, you are referred
 139  * to Jon Ribbens' excellent documentation, which you should have, or which
 140  * may obtained at your friendly local bulletin board or FTP site.  I have
 141  * only marked oddities, or departures from the standard interface.
 142  *
 143  * Hardened speed freaks: have no fear -- all of these interface routines
 144  * is written in hand-crafted assembler, by an expert (me :-) ).  I am
 145  * *not* Acorn, and really do know that _kernel_swi and os_swi are *not*
 146  * the best way to write module veneers.
 147  *
 148  *---- Some notes on naming calls -----------------------------------------*
 149  *
 150  * I have attempted to provide a mechanical translation from the SWI names
 151  * to the veneer calls which is (a) easy to remember, (b) consistent (Acorn
 152  * please note :-( ) and (c) easily fits in with the normal 'style' of C.
 153  * All calls begin with the prefix 'wimpExt_'.  I have then lower-cased the
 154  * first letter of the individual call name.  e.g. wimpExt_plotSprite.
 155  * Some calls return values which aren't always useful.  These have two
 156  * variants: one which does not return the value, and one which does.  The
 157  * latter has an extra parameter (where to place this return value), and a
 158  * '_r' suffix.
 159  *
 160  * Some calls do a lot of things, depending on a reason code.  These are
 161  * handled by having a lot of routines with the call name and a suffix
 162  * describing what the call does.
 163  *
 164  * Other suffices are occasionally added to call names.  These are documented
 165  * with the individual interface.
 166  */
 167
 168 os_error *wimpExt_initialise(wimpExt_features f);
 169 /*
 170  * This call sets WimpExt_CloseDown to be called automatically via the
 171  * atexit system.
 172  */
 173
 174 os_error *wimpExt_slabIcon(wimp_w w,wimp_i i,BOOL popIn);
 175
 176 os_error *wimpExt_redraw(wimp_redrawstr *r);
 177
 178 os_error *wimpExt_action(wimp_eventstr *e);
 179 /*
 180  * Warning -- the event structure may be modified by this call.
 181  */
 182
 183 os_error *wimpExt_iconBarSprite(wimp_i *i,
 184                                 wimpExt_ibarSide s,
 185                                 char *sprite,
 186                                 wimp_ibtype btype);
 187 os_error *wimpExt_iconBarText(wimp_i *i,
 188                               wimpExt_ibarSide s,
 189                               char *sprite,
 190                               char *text,
 191                               wimp_ibtype btype);
 192 /*
 193  * These last two are *not* recommended -- ibicon provides a much better
 194  * may of controlling the icon bar :-)
 195  */
 196
 197 os_error *wimpExt_linkWindows(wimp_w main,wimp_w sub,wimpExt_linkflags f);
 198
 199 os_error *wimpExt_openLinked(wimp_openstr *o);
 200
 201 os_error *wimpExt_closeLinked(wimp_w w);
 202
 203 os_error *wimpExt_unLinkWindows(wimp_w main,wimp_w sub);
 204
 205 os_error *wimpExt_currentTask(void);
 206 /*
 207  * Like all WimpExtension calls that are interested in task handles, this
 208  * one uses wimpt_task() to get it.
 209  */
 210
 211 os_error *wimpExt_loadTemplates(wimp_w handles[],
 212                                 void *bigBuff,
 213                                 char *indirectData,
 214                                 char *indirectEnd,
 215                                 char fontArray[], /* Or *0* for no fonts */
 216                                 char *filename,
 217                                 sprite_area *s);
 218 /*
 219  * I recommend you use tyhe standard template functions instead -- they
 220  * prevent you from creating all the windows on startup.
 221  */
 222
 223 os_error *wimpExt_setIconString(BOOL ellipsis, /* Only if feature code set */
 224                                 wimp_w w,
 225                                 wimp_i i,
 226                                 char *text);
 227
 228 os_error *wimpExt_openWindowTop(wimp_w w);
 229
 230 os_error *wimpExt_setIcon(wimp_w w,wimp_i i,wimpExt_state s);
 231 os_error *wimpExt_setIcon_r(wimp_w w,wimp_i i,wimpExt_state s,BOOL *old);
 232
 233 os_error *wimpExt_getIcon(wimp_w w,wimp_i i,BOOL *old);
 234 os_error *wimpExt_getIcon_t(wimp_w w,wimp_i i,BOOL *old,char **indText);
 235 /*
 236  * The '_t' variant returns the word at iconblock+20 (which would be the
 237  * indirected text of an indirected icon).
 238  */
 239
 240 os_error *wimpExt_setNumberIcon(int base,wimp_w w,wimp_i i,int value);
 241
 242 os_error *wimpExt_getNumberIcon(int base,wimp_w w,wimp_i i,int *value);
 243
 244 os_error *wimpExt_incNumberIcon(int base,
 245                                 wimp_w w,
 246                                 wimp_i i,
 247                                 int max,
 248                                 int step);
 249 os_error *wimpExt_incNumberIcon_r(int base,
 250                                   wimp_w w,
 251                                   wimp_i i,
 252                                   int max,
 253                                   int step,
 254                                   int *value);
 255
 256 os_error *wimpExt_decNumberIcon(int base,
 257                                 wimp_w w,
 258                                 wimp_i i,
 259                                 int min,
 260                                 int step);
 261 os_error *wimpExt_decNumberIcon_r(int base,
 262                                   wimp_w w,
 263                                   wimp_i i,
 264                                   int min,
 265                                   int step,
 266                                   int *value);
 267
 268 os_error *wimpExt_setPointer(char *pointer,int hotx,int hoty);
 269
 270 os_error *wimpExt_divide(int divident,
 271                          int divisor,
 272                          int *quotient,
 273                          int *remainder);
 274 /*
 275  * One doesn't have to see the point -- one just has to write the veneer.
 276  * My suggestion -- use C's built-in divide operator.  Acorn say they've
 277  * put a lot of effort into _kernel_udiv etc.  Don't let them down.  They
 278  * might produce another Style Guide :-/
 279  */
 280
 281 os_error *wimpExt_coloursMenu(wimp_menustr *m,int itemToTick,BOOL backg);
 282
 283 os_error *wimpExt_autoRedraw(wimp_redrawstr *r);
 284
 285 os_error *wimpExt_centreWindow(wimp_wstate *s);
 286
 287 os_error *wimpExt_dragIcon(wimpExt_dragFlags f,
 288                            sprite_area *s,
 289                            wimp_w w,
 290                            wimp_i i,
 291                            char *sprite,
 292                            wimp_box *box);
 293
 294 os_error *wimpExt_putCaretIcon(wimp_w w,wimp_i i);
 295
 296 os_error *wimpExt_openDialogue(wimp_w,int offx,int offy);
 297
 298 os_error *wimpExt_checkWindowOpen(wimp_w w,BOOL *open);
 299
 300 os_error *wimpExt_copyString(char *to,char *from);
 301 /*
 302  * If I were you, I'd use strcpy.  Still, this works on char-terminated
 303  * strings, and NULL-terminates the destination.  WimpExtension veterans
 304  * will notice I've swapped the arguments round.  This is to make it more
 305  * like strcpy, which C users have probably encountered already.  It saves
 306  * thought time.
 307  */
 308
 309 os_error *wimpExt_setWindowTitle(wimp_w w,char *string);
 310
 311 os_error *wimpExt_setIconStringN(BOOL ellipsis, /* Only if feature code set*/
 312                                  wimp_w w,
 313                                  wimp_i i,
 314                                  char *text);
 315
 316 char *wimpExt_findLeaf(char *path);
 317 /*
 318  * Purists will note that I have deviated from the convention of returning
 319  * the error information.  This is because (a) it makes the calling more
 320  * natural, and (b) this SWI doesn't have any errors anyway (I checked with
 321  * Zap :-) ).
 322  */
 323
 324 os_error *wimpExt_limitPointer(wimp_w w);
 325
 326 os_error *wimpExt_releasePointer(void);
 327
 328 os_error *wimpExt_openFullSize(wimp_w w,wimp_w behind);
 329
 330 os_error *wimpExt_loadRAMTemplate(wimp_wind *buf,
 331                                   char **indStart,
 332                                   char *indEnd,
 333                                   char fonts[], /* Ignored in this release */
 334                                   void *temp);
 335 /*
 336  * I can't see the use of it myself.  Still, it's there, so I've got to do
 337  * the veneer for it...
 338  */
 339
 340 os_error *wimpExt_openRequester(char *title,
 341                                 char *text,
 342                                 char *buttons[],
 343                                 int escape);
 344
 345 os_error *wimpExt_closeRequester(void);
 346
 347 os_error *wimpExt_hideLink(wimp_w main,wimp_w sub);
 348
 349 os_error *wimpExt_unHideLink(wimp_w main,wimp_w sub);
 350
 351 os_error *wimpExt_sendHelp(char *text,wimp_msgstr *m);
 352
 353 os_error *wimpExt_sendWimpHelp(char *ref,char *document);
 354 /*
 355  * This call may change, depending on Diamond's final name.  There will also
 356  * be Diamond Help Viewer support in Steel anyway.
 357  */
 358
 359 os_error *wimpExt_createMenu(wimp_menustr *m,int x,int y);
 360
 361 os_error *wimpExt_reCreateMenu(void);
 362
 363 os_error *wimpExt_shadeEntry(wimp_menustr *m,int option,wimpExt_state s);
 364 os_error *wimpExt_shadeEntry_r(wimp_menustr *m,
 365                                int option,
 366                                wimpExt_state s,
 367                                BOOL *old);
 368
 369 os_error *wimpExt_tickEntry(wimp_menustr *m,int option,wimpExt_state s);
 370 os_error *wimpExt_tickEntry_r(wimp_menustr *m,
 371                               int option,
 372                               wimpExt_state s,
 373                               BOOL *old);
 374
 375 os_error *wimpExt_setIconColour(wimp_w w,wimp_i i,int fg,int bg);
 376 os_error *wimpExt_setIconColour_r(wimp_w w,wimp_i i,int *fg,int *bg);
 377
 378 os_error *wimpExt_shadeIcon(wimp_w w,wimp_i i,wimpExt_state s);
 379 os_error *wimpExt_shadeIcon_r(wimp_w w,wimp_i i,wimpExt_state s,BOOL *old);
 380
 381 /*
 382  * WimpExt_PlotSprite should not be used.  Use wimpExt_spriteOp_plot
 383  * instead.
 384  */
 385
 386 /*
 387  * WimpExt_RedrawDraw should not be used.  Use wimpExt_drawOp_redraw
 388  * instead.
 389  */
 390
 391 os_error *wimpExt_prePoll(void);
 392
 393 os_error *wimpExt_setExtent(wimp_redrawstr *r);
 394
 395 os_error *wimpExt_moveCaret(int *key,wimp_w w,wimp_i i);
 396
 397 os_error *wimpExt_getFontMenu(BOOL shadeSystem,char *title,wimp_menustr **m);
 398 os_error *wimpExt_decodeFontMenu(char *name,wimp_eventstr *e);
 399 /*
 400  * I recommend that you use the Steel font menu routines -- they're much
 401  * nicer :-).  WimpExtension doesn't do item ticking etc.
 402  */
 403
 404 /* --- WimpExt_ControlImmediate --- */
 405
 406 os_error *wimpExt_controlImmediate_close(void);
 407 os_error *wimpExt_controlImmediate_checkMouse(wimp_i *icon);
 408 os_error *wimpExt_controlImmediate_openAndCheck(char *title,
 409                                                 char *text,
 410                                                 char *buttons[],
 411                                                 int escape
 412                                                 wimp_i *icon);
 413 os_error *wimpExt_controlImmediate_redrawIcon(wimp_i i);
 414 os_error *wimpExt_controlImmediate_slabIcon(wimp_i i,BOOL slabIn);
 415 os_error *wimpExt_controlImmediate_limitPtr(void);
 416 os_error *wimpExt_controlImmediate_redrawBorder(wimp_i i);
 417 os_error *wimpExt_controlImmediate_redrawIcon(wimp_icon *i,int ox,int oy);
 418 os_error *wimpExt_controlImmediate_fromWindow(wimp_wind *w,wimp_i *icon);
 419
 420 /* --- WimpExt_Heap --- *
 421  *
 422  * Fun time...
 423  */
 424
 425 os_error *wimpExt_heap_initStd(void *base,int anchors);
 426 os_error *wimpExt_heap_describe(wimpExt_heapDescription *h);
 427 os_error *wimpExt_heap_alloc(wimpExt_heapAnchor **a,size_t size);
 428 os_error *wimpExt_heap_free(void *p);
 429 os_error *wimpExt_heap_realloc(wimpExt_heapAnchor **a,void *p,size_t size);
 430 os_error *wimpExt_heap_tidy(void);
 431 os_error *wimpExt_heap_compact(void);
 432 os_error *wimpExt_heap_findAnchor(wimpExt_heapAnchor **a,void *p);
 433 os_error *wimpExt_heap_fix(void);
 434 os_error *wimpExt_heap_forceUnfix(void);
 435 os_error *wimpExt_heap_unfix(void);
 436 os_error *wimpExt_heap_addAnchors(int anchors,BOOL *worked);
 437 os_error *wimpExt_heap_allocAddAnchors(wimpExt_heapAnchor **a,size_t size);
 438 os_error *wimpExt_heap_freeAll(void);
 439 os_error *wimpExt_heap_select(void *heap);
 440 os_error *wimpExt_heap_select_r(void *heap,void **oldHeap,void **newHeap);
 441 os_error *wimpExt_heap_relocate(void);
 442 os_error *wimpExt_heap_createInHeap(void **heap,int anchors);
 443
 444 os_error *wimpExt_memCopy(void *to,void *from,size_t for);
 445 /*
 446  * Again, I have switched the order of arguments.  I suggest you use memcpy
 447  * or (better) memmove for these jobs -- it's highly optimised now, and
 448  * generally really good.
 449  */
 450
 451 os_error *wimpExt_dataSave(size_t size,
 452                            char *name,
 453                            int ftype,
 454                            void *data,
 455                            BOOL dontSaveToSelf,
 456                            wimp_mousestr *m);
 457 os_error *wimpExt_dataSave_r(size_t size,
 458                              char *name,
 459                              int ftype,
 460                              void *data,
 461                              BOOL dontSaveToSelf,
 462                              wimp_mousestr *m);
 463
 464
 465
 466 #endif