4 * C access to DoggySoft's WimpExtension module
6 * © 1993-1998 Straylight
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.
31 /*----- Required headers --------------------------------------------------*/
41 /*----- Data structures and things ----------------------------------------*/
43 typedef enum wimpExt_features /* For wimpExt_initialise */
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,
55 wimpExt_SCROLLONCARETMOVE =1<<10,
56 wimpExt_TABDOESNTMOVECARET =1<<11
60 typedef enum wimpExt_ibarSide
67 typedef enum wimpExt_linkflags
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 */
77 typedef enum wimpExt_templateFlags
79 wimpExt_HCENTRE =1<<0,
80 wimpExt_NOCREATE =1<<1,
83 wimpExt_templateFlags;
85 typedef enum wimpExt_state
93 #define wimpExt_WIMPAREA ((sprite_area *)1)
94 #define wimpExt_SYSTEMAREA ((sprite_area *)0)
96 typedef enum wimpExt_dragFlags
98 /* --- Sprite positionings --- */
101 wimpExt_HRIGHT =2<<0,
106 /* --- Mouse bounding box --- */
107 wimpExt_SCREEN =0<<4,
108 wimpExt_WINDOW =1<<4,
111 /* --- Other things --- */
112 wimpExt_BOUNDSPRITE =1<<6,
113 wimpExt_SHADOW =1<<7,
114 wimpExt_FORCESPRITE =1<<8
117 #define wimpExt_REQUESTER (-3)
119 #define wimpExt_STANDARDHELP ((void *)1)
120 #define wimpExt_NOCHANGEHEAP ((void *)-1)
121 #define wimpExt_NOHEAP((void *)0)
123 typedef struct wimpExt_heapDescription
132 wimpExt_heapDescription;
134 typedef void *wimpExt_heapAnchor;
136 /*----- Routines ----------------------------------------------------------*
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.
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.
148 *---- Some notes on naming calls -----------------------------------------*
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
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.
164 * Other suffices are occasionally added to call names. These are documented
165 * with the individual interface.
168 os_error *wimpExt_initialise(wimpExt_features f);
170 * This call sets WimpExt_CloseDown to be called automatically via the
174 os_error *wimpExt_slabIcon(wimp_w w,wimp_i i,BOOL popIn);
176 os_error *wimpExt_redraw(wimp_redrawstr *r);
178 os_error *wimpExt_action(wimp_eventstr *e);
180 * Warning -- the event structure may be modified by this call.
183 os_error *wimpExt_iconBarSprite(wimp_i *i,
187 os_error *wimpExt_iconBarText(wimp_i *i,
193 * These last two are *not* recommended -- ibicon provides a much better
194 * may of controlling the icon bar :-)
197 os_error *wimpExt_linkWindows(wimp_w main,wimp_w sub,wimpExt_linkflags f);
199 os_error *wimpExt_openLinked(wimp_openstr *o);
201 os_error *wimpExt_closeLinked(wimp_w w);
203 os_error *wimpExt_unLinkWindows(wimp_w main,wimp_w sub);
205 os_error *wimpExt_currentTask(void);
207 * Like all WimpExtension calls that are interested in task handles, this
208 * one uses wimpt_task() to get it.
211 os_error *wimpExt_loadTemplates(wimp_w handles[],
215 char fontArray[], /* Or *0* for no fonts */
219 * I recommend you use tyhe standard template functions instead -- they
220 * prevent you from creating all the windows on startup.
223 os_error *wimpExt_setIconString(BOOL ellipsis, /* Only if feature code set */
228 os_error *wimpExt_openWindowTop(wimp_w w);
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);
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);
236 * The '_t' variant returns the word at iconblock+20 (which would be the
237 * indirected text of an indirected icon).
240 os_error *wimpExt_setNumberIcon(int base,wimp_w w,wimp_i i,int value);
242 os_error *wimpExt_getNumberIcon(int base,wimp_w w,wimp_i i,int *value);
244 os_error *wimpExt_incNumberIcon(int base,
249 os_error *wimpExt_incNumberIcon_r(int base,
256 os_error *wimpExt_decNumberIcon(int base,
261 os_error *wimpExt_decNumberIcon_r(int base,
268 os_error *wimpExt_setPointer(char *pointer,int hotx,int hoty);
270 os_error *wimpExt_divide(int divident,
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 :-/
281 os_error *wimpExt_coloursMenu(wimp_menustr *m,int itemToTick,BOOL backg);
283 os_error *wimpExt_autoRedraw(wimp_redrawstr *r);
285 os_error *wimpExt_centreWindow(wimp_wstate *s);
287 os_error *wimpExt_dragIcon(wimpExt_dragFlags f,
294 os_error *wimpExt_putCaretIcon(wimp_w w,wimp_i i);
296 os_error *wimpExt_openDialogue(wimp_w,int offx,int offy);
298 os_error *wimpExt_checkWindowOpen(wimp_w w,BOOL *open);
300 os_error *wimpExt_copyString(char *to,char *from);
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
309 os_error *wimpExt_setWindowTitle(wimp_w w,char *string);
311 os_error *wimpExt_setIconStringN(BOOL ellipsis, /* Only if feature code set*/
316 char *wimpExt_findLeaf(char *path);
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
324 os_error *wimpExt_limitPointer(wimp_w w);
326 os_error *wimpExt_releasePointer(void);
328 os_error *wimpExt_openFullSize(wimp_w w,wimp_w behind);
330 os_error *wimpExt_loadRAMTemplate(wimp_wind *buf,
333 char fonts[], /* Ignored in this release */
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...
340 os_error *wimpExt_openRequester(char *title,
345 os_error *wimpExt_closeRequester(void);
347 os_error *wimpExt_hideLink(wimp_w main,wimp_w sub);
349 os_error *wimpExt_unHideLink(wimp_w main,wimp_w sub);
351 os_error *wimpExt_sendHelp(char *text,wimp_msgstr *m);
353 os_error *wimpExt_sendWimpHelp(char *ref,char *document);
355 * This call may change, depending on Diamond's final name. There will also
356 * be Diamond Help Viewer support in Steel anyway.
359 os_error *wimpExt_createMenu(wimp_menustr *m,int x,int y);
361 os_error *wimpExt_reCreateMenu(void);
363 os_error *wimpExt_shadeEntry(wimp_menustr *m,int option,wimpExt_state s);
364 os_error *wimpExt_shadeEntry_r(wimp_menustr *m,
369 os_error *wimpExt_tickEntry(wimp_menustr *m,int option,wimpExt_state s);
370 os_error *wimpExt_tickEntry_r(wimp_menustr *m,
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);
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);
382 * WimpExt_PlotSprite should not be used. Use wimpExt_spriteOp_plot
387 * WimpExt_RedrawDraw should not be used. Use wimpExt_drawOp_redraw
391 os_error *wimpExt_prePoll(void);
393 os_error *wimpExt_setExtent(wimp_redrawstr *r);
395 os_error *wimpExt_moveCaret(int *key,wimp_w w,wimp_i i);
397 os_error *wimpExt_getFontMenu(BOOL shadeSystem,char *title,wimp_menustr **m);
398 os_error *wimpExt_decodeFontMenu(char *name,wimp_eventstr *e);
400 * I recommend that you use the Steel font menu routines -- they're much
401 * nicer :-). WimpExtension doesn't do item ticking etc.
404 /* --- WimpExt_ControlImmediate --- */
406 os_error *wimpExt_controlImmediate_close(void);
407 os_error *wimpExt_controlImmediate_checkMouse(wimp_i *icon);
408 os_error *wimpExt_controlImmediate_openAndCheck(char *title,
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);
420 /* --- WimpExt_Heap --- *
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);
444 os_error *wimpExt_memCopy(void *to,void *from,size_t for);
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.
451 os_error *wimpExt_dataSave(size_t size,
457 os_error *wimpExt_dataSave_r(size_t size,