/* * wimpExt.h * * C access to DoggySoft's WimpExtension module * * © 1993-1998 Straylight */ /*----- Licensing note ----------------------------------------------------* * * This file is part of Straylight's Steel library. * * Steel is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2, or (at your option) * any later version. * * Steel is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with Steel. If not, write to the Free Software Foundation, * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef __wimpExt_h #define __wimpExt_h /*----- Required headers --------------------------------------------------*/ #ifndef __os_h #include "os.h" #endif #ifndef __wimp_h #include "wimp.h" #endif /*----- Data structures and things ----------------------------------------*/ typedef enum wimpExt_features /* For wimpExt_initialise */ { wimpExt_SEMIAUTOSLAB =1<<0, wimpExt_AUTORECREATEMENU =1<<1, wimpExt_USEFONTMENUS =1<<2, wimpExt_AUTOCOMPACTHEAP =1<<3, wimpExt_CORRECTRADIO =1<<4, wimpExt_SEMIAUTOHELP =1<<5, wimpExt_ALTARGSINSETFLAGS =1<<6, wimpExt_MAYBEADDELLIPSIS =1<<7, wimpExt_AUTOMOVECARET =1<<8, wimpExt_USEESG =1<<9, wimpExt_SCROLLONCARETMOVE =1<<10, wimpExt_TABDOESNTMOVECARET =1<<11 } wimpExt_features; typedef enum wimpExt_ibarSide { wimpExt_IBLEFT=-2, wimpExt_IBRIGHT=-1 } wimpExt_ibarSide; typedef enum wimpExt_linkflags { wimpExt_CLIPLEFT =1<<0, wimpExt_CLIPRIGHT =1<<1, wimpExt_CLIPABOVE =1<<2, wimpExt_CLIPBELOW =1<<3, wimpExt_HIDELINK =~0x7FFFFFFF /* Yipes */ } wimpExt_linkflags; typedef enum wimpExt_templateFlags { wimpExt_HCENTRE =1<<0, wimpExt_NOCREATE =1<<1, wimpExt_VCENTRE =1<<2 } wimpExt_templateFlags; typedef enum wimpExt_state { wimpExt_RESET, wimpExt_SET, wimpExt_TOGGLE } wimpExt_state; #define wimpExt_WIMPAREA ((sprite_area *)1) #define wimpExt_SYSTEMAREA ((sprite_area *)0) typedef enum wimpExt_dragFlags { /* --- Sprite positionings --- */ wimpExt_HLEFT =0<<0, wimpExt_HMID =1<<0, wimpExt_HRIGHT =2<<0, wimpExt_VBOT =0<<2, wimpExt_VMID =1<<2, wimpExt_VTOP =2<<2, /* --- Mouse bounding box --- */ wimpExt_SCREEN =0<<4, wimpExt_WINDOW =1<<4, wimpExt_GIVEN =2<<4, /* --- Other things --- */ wimpExt_BOUNDSPRITE =1<<6, wimpExt_SHADOW =1<<7, wimpExt_FORCESPRITE =1<<8 } #define wimpExt_REQUESTER (-3) #define wimpExt_STANDARDHELP ((void *)1) #define wimpExt_NOCHANGEHEAP ((void *)-1) #define wimpExt_NOHEAP((void *)0) typedef struct wimpExt_heapDescription { void *currHeap; int largestBlock; int totFree; int heapUsed; int totAnchors; int anchorsUsed; } wimpExt_heapDescription; typedef void *wimpExt_heapAnchor; /*----- Routines ----------------------------------------------------------* * * These aren't described in great detail here. Instead, you are referred * to Jon Ribbens' excellent documentation, which you should have, or which * may obtained at your friendly local bulletin board or FTP site. I have * only marked oddities, or departures from the standard interface. * * Hardened speed freaks: have no fear -- all of these interface routines * is written in hand-crafted assembler, by an expert (me :-) ). I am * *not* Acorn, and really do know that _kernel_swi and os_swi are *not* * the best way to write module veneers. * *---- Some notes on naming calls -----------------------------------------* * * I have attempted to provide a mechanical translation from the SWI names * to the veneer calls which is (a) easy to remember, (b) consistent (Acorn * please note :-( ) and (c) easily fits in with the normal 'style' of C. * All calls begin with the prefix 'wimpExt_'. I have then lower-cased the * first letter of the individual call name. e.g. wimpExt_plotSprite. * Some calls return values which aren't always useful. These have two * variants: one which does not return the value, and one which does. The * latter has an extra parameter (where to place this return value), and a * '_r' suffix. * * Some calls do a lot of things, depending on a reason code. These are * handled by having a lot of routines with the call name and a suffix * describing what the call does. * * Other suffices are occasionally added to call names. These are documented * with the individual interface. */ os_error *wimpExt_initialise(wimpExt_features f); /* * This call sets WimpExt_CloseDown to be called automatically via the * atexit system. */ os_error *wimpExt_slabIcon(wimp_w w,wimp_i i,BOOL popIn); os_error *wimpExt_redraw(wimp_redrawstr *r); os_error *wimpExt_action(wimp_eventstr *e); /* * Warning -- the event structure may be modified by this call. */ os_error *wimpExt_iconBarSprite(wimp_i *i, wimpExt_ibarSide s, char *sprite, wimp_ibtype btype); os_error *wimpExt_iconBarText(wimp_i *i, wimpExt_ibarSide s, char *sprite, char *text, wimp_ibtype btype); /* * These last two are *not* recommended -- ibicon provides a much better * may of controlling the icon bar :-) */ os_error *wimpExt_linkWindows(wimp_w main,wimp_w sub,wimpExt_linkflags f); os_error *wimpExt_openLinked(wimp_openstr *o); os_error *wimpExt_closeLinked(wimp_w w); os_error *wimpExt_unLinkWindows(wimp_w main,wimp_w sub); os_error *wimpExt_currentTask(void); /* * Like all WimpExtension calls that are interested in task handles, this * one uses wimpt_task() to get it. */ os_error *wimpExt_loadTemplates(wimp_w handles[], void *bigBuff, char *indirectData, char *indirectEnd, char fontArray[], /* Or *0* for no fonts */ char *filename, sprite_area *s); /* * I recommend you use tyhe standard template functions instead -- they * prevent you from creating all the windows on startup. */ os_error *wimpExt_setIconString(BOOL ellipsis, /* Only if feature code set */ wimp_w w, wimp_i i, char *text); os_error *wimpExt_openWindowTop(wimp_w w); os_error *wimpExt_setIcon(wimp_w w,wimp_i i,wimpExt_state s); os_error *wimpExt_setIcon_r(wimp_w w,wimp_i i,wimpExt_state s,BOOL *old); os_error *wimpExt_getIcon(wimp_w w,wimp_i i,BOOL *old); os_error *wimpExt_getIcon_t(wimp_w w,wimp_i i,BOOL *old,char **indText); /* * The '_t' variant returns the word at iconblock+20 (which would be the * indirected text of an indirected icon). */ os_error *wimpExt_setNumberIcon(int base,wimp_w w,wimp_i i,int value); os_error *wimpExt_getNumberIcon(int base,wimp_w w,wimp_i i,int *value); os_error *wimpExt_incNumberIcon(int base, wimp_w w, wimp_i i, int max, int step); os_error *wimpExt_incNumberIcon_r(int base, wimp_w w, wimp_i i, int max, int step, int *value); os_error *wimpExt_decNumberIcon(int base, wimp_w w, wimp_i i, int min, int step); os_error *wimpExt_decNumberIcon_r(int base, wimp_w w, wimp_i i, int min, int step, int *value); os_error *wimpExt_setPointer(char *pointer,int hotx,int hoty); os_error *wimpExt_divide(int divident, int divisor, int *quotient, int *remainder); /* * One doesn't have to see the point -- one just has to write the veneer. * My suggestion -- use C's built-in divide operator. Acorn say they've * put a lot of effort into _kernel_udiv etc. Don't let them down. They * might produce another Style Guide :-/ */ os_error *wimpExt_coloursMenu(wimp_menustr *m,int itemToTick,BOOL backg); os_error *wimpExt_autoRedraw(wimp_redrawstr *r); os_error *wimpExt_centreWindow(wimp_wstate *s); os_error *wimpExt_dragIcon(wimpExt_dragFlags f, sprite_area *s, wimp_w w, wimp_i i, char *sprite, wimp_box *box); os_error *wimpExt_putCaretIcon(wimp_w w,wimp_i i); os_error *wimpExt_openDialogue(wimp_w,int offx,int offy); os_error *wimpExt_checkWindowOpen(wimp_w w,BOOL *open); os_error *wimpExt_copyString(char *to,char *from); /* * If I were you, I'd use strcpy. Still, this works on char-terminated * strings, and NULL-terminates the destination. WimpExtension veterans * will notice I've swapped the arguments round. This is to make it more * like strcpy, which C users have probably encountered already. It saves * thought time. */ os_error *wimpExt_setWindowTitle(wimp_w w,char *string); os_error *wimpExt_setIconStringN(BOOL ellipsis, /* Only if feature code set*/ wimp_w w, wimp_i i, char *text); char *wimpExt_findLeaf(char *path); /* * Purists will note that I have deviated from the convention of returning * the error information. This is because (a) it makes the calling more * natural, and (b) this SWI doesn't have any errors anyway (I checked with * Zap :-) ). */ os_error *wimpExt_limitPointer(wimp_w w); os_error *wimpExt_releasePointer(void); os_error *wimpExt_openFullSize(wimp_w w,wimp_w behind); os_error *wimpExt_loadRAMTemplate(wimp_wind *buf, char **indStart, char *indEnd, char fonts[], /* Ignored in this release */ void *temp); /* * I can't see the use of it myself. Still, it's there, so I've got to do * the veneer for it... */ os_error *wimpExt_openRequester(char *title, char *text, char *buttons[], int escape); os_error *wimpExt_closeRequester(void); os_error *wimpExt_hideLink(wimp_w main,wimp_w sub); os_error *wimpExt_unHideLink(wimp_w main,wimp_w sub); os_error *wimpExt_sendHelp(char *text,wimp_msgstr *m); os_error *wimpExt_sendWimpHelp(char *ref,char *document); /* * This call may change, depending on Diamond's final name. There will also * be Diamond Help Viewer support in Steel anyway. */ os_error *wimpExt_createMenu(wimp_menustr *m,int x,int y); os_error *wimpExt_reCreateMenu(void); os_error *wimpExt_shadeEntry(wimp_menustr *m,int option,wimpExt_state s); os_error *wimpExt_shadeEntry_r(wimp_menustr *m, int option, wimpExt_state s, BOOL *old); os_error *wimpExt_tickEntry(wimp_menustr *m,int option,wimpExt_state s); os_error *wimpExt_tickEntry_r(wimp_menustr *m, int option, wimpExt_state s, BOOL *old); os_error *wimpExt_setIconColour(wimp_w w,wimp_i i,int fg,int bg); os_error *wimpExt_setIconColour_r(wimp_w w,wimp_i i,int *fg,int *bg); os_error *wimpExt_shadeIcon(wimp_w w,wimp_i i,wimpExt_state s); os_error *wimpExt_shadeIcon_r(wimp_w w,wimp_i i,wimpExt_state s,BOOL *old); /* * WimpExt_PlotSprite should not be used. Use wimpExt_spriteOp_plot * instead. */ /* * WimpExt_RedrawDraw should not be used. Use wimpExt_drawOp_redraw * instead. */ os_error *wimpExt_prePoll(void); os_error *wimpExt_setExtent(wimp_redrawstr *r); os_error *wimpExt_moveCaret(int *key,wimp_w w,wimp_i i); os_error *wimpExt_getFontMenu(BOOL shadeSystem,char *title,wimp_menustr **m); os_error *wimpExt_decodeFontMenu(char *name,wimp_eventstr *e); /* * I recommend that you use the Steel font menu routines -- they're much * nicer :-). WimpExtension doesn't do item ticking etc. */ /* --- WimpExt_ControlImmediate --- */ os_error *wimpExt_controlImmediate_close(void); os_error *wimpExt_controlImmediate_checkMouse(wimp_i *icon); os_error *wimpExt_controlImmediate_openAndCheck(char *title, char *text, char *buttons[], int escape wimp_i *icon); os_error *wimpExt_controlImmediate_redrawIcon(wimp_i i); os_error *wimpExt_controlImmediate_slabIcon(wimp_i i,BOOL slabIn); os_error *wimpExt_controlImmediate_limitPtr(void); os_error *wimpExt_controlImmediate_redrawBorder(wimp_i i); os_error *wimpExt_controlImmediate_redrawIcon(wimp_icon *i,int ox,int oy); os_error *wimpExt_controlImmediate_fromWindow(wimp_wind *w,wimp_i *icon); /* --- WimpExt_Heap --- * * * Fun time... */ os_error *wimpExt_heap_initStd(void *base,int anchors); os_error *wimpExt_heap_describe(wimpExt_heapDescription *h); os_error *wimpExt_heap_alloc(wimpExt_heapAnchor **a,size_t size); os_error *wimpExt_heap_free(void *p); os_error *wimpExt_heap_realloc(wimpExt_heapAnchor **a,void *p,size_t size); os_error *wimpExt_heap_tidy(void); os_error *wimpExt_heap_compact(void); os_error *wimpExt_heap_findAnchor(wimpExt_heapAnchor **a,void *p); os_error *wimpExt_heap_fix(void); os_error *wimpExt_heap_forceUnfix(void); os_error *wimpExt_heap_unfix(void); os_error *wimpExt_heap_addAnchors(int anchors,BOOL *worked); os_error *wimpExt_heap_allocAddAnchors(wimpExt_heapAnchor **a,size_t size); os_error *wimpExt_heap_freeAll(void); os_error *wimpExt_heap_select(void *heap); os_error *wimpExt_heap_select_r(void *heap,void **oldHeap,void **newHeap); os_error *wimpExt_heap_relocate(void); os_error *wimpExt_heap_createInHeap(void **heap,int anchors); os_error *wimpExt_memCopy(void *to,void *from,size_t for); /* * Again, I have switched the order of arguments. I suggest you use memcpy * or (better) memmove for these jobs -- it's highly optimised now, and * generally really good. */ os_error *wimpExt_dataSave(size_t size, char *name, int ftype, void *data, BOOL dontSaveToSelf, wimp_mousestr *m); os_error *wimpExt_dataSave_r(size_t size, char *name, int ftype, void *data, BOOL dontSaveToSelf, wimp_mousestr *m); #endif