home *** CD-ROM | disk | FTP | other *** search
- /**** ewindow.h ****/
- /* Handles windows with euclid pictures in them
- * By Paul Field
- * See !ReadMe file for distribution/modification restrictions
- *
- * N.B. To define the position/size/work area etc of each ewindow, use
- * 'template_syshandle("ewindow")' to get at the window's template and alter
- * it to suit you before you call 'ewindow_create'.
- * Notice that the euclid picture is drawn with its origin at (0,0) so you will
- * probably need negative work area coordinates.
- * I may alter 'ewindow_create' or add some new functions to allow you to define
- * features of ewindows.
- *
- * Things you should be careful of :
- * 1) This module catches palette and mode changes using an 'unknown event processor'
- * (see win.h). If you use unknown event processors yourself make sure they do not
- * block palette and mode change messages.
- * 2) Palette changes cause sprites to be redrawn unless they are in raytracing style.
- * This is likely to change. I will probably add a function that allows you to
- * choose whether pictures are redrawn on palette changes.
- * 3) This module uses 'alarm.h' to handle multitasking drawing. Under various
- * circumstances it will remove all alarms with a particular ewindow as a handle.
- * (I can probably get round this if it is a problem to anyone).
- * 4) This module will also remove processes from a cache's pending queue if they
- * have a particular ewindow as a handle. (Again, I can probably get round this).
- * 5) Don't change the drawing cache of a structure once it is registered with a window.
- * (If anyone needs to do this - let me know)
- * 6) If you are using multitasking windows then a structure's drawing cache may
- * be in use at any time. If you need to use the cache for something
- * (e.g. drawing into a sprite) then use 'cache_callwhenfree()' to call
- * your routine. If none of your windows are multitasking or every picture has its
- * own drawing cache then you do not need to do this.
- * 7) Euclid draws the graphs in inverse in 2 and 4 colour modes on the desktop.
- * I have arranged the display of sprites so that they do this too.
- * This means that 256-colour sprites are plotted using colourtrans while
- * 2,4 and 16-colour sprites are plotted useing the desktop colours.
- * I don't know if this matters to anyone - but I'd thought I'd mention it.
- *
- * Also note :
- * 1) The module should use flex and it is written so that registering 'flex_budge'
- * with _kernel_register_slotextend() should work.
- * Unfortunately, Euclid doesn't like it if the flex block
- * moves between it drawing sections of a multitasking picture.
- * Tony Cheal (Euclid's author) has told me that it is impractical to move the
- * cache around during drawing so, for the moment, I have used 'heap_alloc' and
- * you shouldn't use 'flex_budge'.
- * I have an idea that may allow the cache and picture (and maybe a sprite
- * being drawn to) to all be in flex blocks. It may be implemented in a later
- * version of the module. (If you particularly need the feature contect me
- * and badger me to put it in).
- *
- * If you use the sprite mode in any windows then you should make its use
- * user-configurable - the user has a fair idea how much memory is needed for other
- * things and so should decide whether to have this memory-hungry feature or not.
- *
- * Using sprites in windows can take up a lot of memory, so I may try using some sort of
- * compression. Decompressing a sprite should still be much faster than asking euclid
- * to redraw the picture.
- *
- * IMPORTANT :
- * I really need feedback about this module, especially comments on the sprite
- * and multitasking features. I need to know whether function calls for setting up
- * windows are easy or cumbersome to use and if you'd prefer a different way
- * of doing things. For example, instead of including 'closefn' as a parameter
- * in ewindow_create I could add a function 'ewindow_registerclosefn(...)' or
- * perhaps a function 'ewindow_registereventhandler(...)' which passes all window
- * events onto your function.
- * I could also add event handlers for events such as:
- * update finished
- * draw called (could be used to access 'infoblock' or
- * to draw in 'extras' over the picture)
- * I also need to know what aspects of windows you need to change
- * (e.g. workarea, picture displayed within, cache).
- * To make this module work I need to know what you are trying to do with it
- * and what problems it gives you.
- */
-
- #ifndef __ewindow_h
- #define __ewindow_h
-
- #include "euclid.h"
- #include "wimp.h"
-
- typedef struct ewindow_str *ewindow; /* An opaque type */
-
-
- typedef void (*ewindow_closefn) (ewindow, void *);
-
- ewindow ewindow_create(const char *title, euclid_drawstyle, euclid_header *structure,
- const char *camera, ewindow_closefn, void *handle);
- /* Creates a window from the Template 'ewindow' which displays the picture
- * refered to by 'structure' in the style given as seen from 'camera'.
- * (camera may be NULL).
- * If the user clicks on the window's 'close' icon 'ewindow_closefn' will be called
- * (with 'handle' as its second argument) so that you can :
- * i) Query that the user really wants to close the window
- * ii) Tidy up any data structures you might have
- * iii) Either close or destroy the window
- *
- * Returns a window structure or NULL if there was not enough memory.
- * You may have multiple windows open.
- * (Window mode defaults to no sprite and no timeout).
- * You should have called 'template_init' and 'flex_init' before you call this.
- * (And for the moment 'heap_init' must be called too - this should not be necessary
- * in later versions)
- */
-
- typedef enum ewindow_spritemode
- { ewindow_smcurrent = -2, ewindow_smdynamic
- }
- ewindow_spritemode;
-
- void ewindow_usesprite(ewindow ew, BOOL sprite, ewindow_spritemode);
- /* If 'sprite' is TRUE the window will attempt to draw the euclid picture in a sprite
- * and then use this during window redraws (which speeds them up considerably).
- * If there is not enough memory to create a sprite then the window will
- * use euclid to redraw the screen until the memory is available. (It detects
- * this on mode and palette changes).
- * 'ewindow_create' defaults to not using sprites.
- * The sprite mode parameter specifies the mode of the sprite. There are two
- * special values :
- * ewindow_smcurrent - use the current screen mode as the sprite mode
- * ewindow_smdynamic - use the current screen mode as the sprite mode and whenever
- * the screenmode changes recreate and redraw the sprite in the
- * new mode. (Also redraws on palette changes).
- */
-
- void ewindow_timing(ewindow ew, char timeout, unsigned int drawgap);
- /* Drawing euclid pictures usually hogs the processor. This call allows picture
- * drawing to occur in several steps (vital if you are going to use the raytracing
- * style). 'timeout' is the number of centiseconds that euclid will spend drawing
- * the picture at one time (roughly).
- * timeout == 0 - no timeout
- * timeout == 0xff - infinite timeout (keep going until mouse event)
- * 'drawgap' is the number of centiseconds between 'spurts' of drawing.
- * 'ewindow_create' defaults to no timeout.
- *
- * Currently multitasking only occurs if a sprite is being used in the window.
- * It is possible (although difficult) to perform a multitasking draw without
- * using sprites and I might try to do this in a later version if I think it is
- * worth the effort.
- */
-
- void ewindow_closeoptions(ewindow ew, BOOL freesprite);
- /* If the 'freesprite' is 'TRUE' then whenever the window is closed any sprite
- * memory associated with it will be freed, if it is 'FALSE' the sprite remains
- * intact and any processes (i.e. drawing) continue to work on it.
- *
- * The option set using this call only has an effect when the 'ewindow_close'
- * is called.
- * This call is mainly useful if you are ray-tracing since you may wish to close
- * the window onto the ray-traced picture without losing the picture.
- * 'ewindow_create' defaults to 'freesprite = TRUE'.
- */
-
- BOOL ewindow_hassprite(ewindow ew);
- /* Returns TRUE if the window has a sprite associated with it.
- */
-
- BOOL ewindow_sprite(ewindow ew, sprite_area ***area, int *offset);
- /* Returns TRUE if the window has a sprite associated with it and returns
- * details of the sprite in 'area' and 'offset'.
- * (Be careful the sprite may not be completely drawn - use 'ewindow_spritecomplete'
- * to check this)
- * Don't be scared by the triple-indirection, this is necessary because the sprite
- * area is a flex block. You should use the call like this :
- * { sprite_area **area;
- * int offset;
- *
- * if (ewindow_sprite(ew, &area, &offset))
- * { sprite_id id;
- *
- * id.tag = sprite_id_addr;
- * id.s.addr = (char *)(*area) + offset;
- * || Now you have a direct reference (id.s.addr) don't do anything that
- * || might move the flex block (see Acorn ANSI C Release 4 manual pp363-4)
- * sprite_xxxx(*area, &id, ....);
- * }
- * }
- * Do not alter the thing that 'area' points to, i.e. don't do anything like
- * '*area = NULL' or attempt to free it, unless you would like your program
- * not to work.
- */
-
- BOOL ewindow_updatecomplete(ewindow ew);
- /* Window using sprite :
- * Returns TRUE if the sprite is completely drawn.
- * (i.e. will return FALSE if the sprite is not drawn or is part way through
- * being drawn (multitasking pictures only)).
- * No sprite :
- * Returns TRUE if the window has no updates pending
- */
-
- void ewindow_setstyle(ewindow ew, euclid_drawstyle);
- /* Changes the drawing style of the window. If the style is different from before
- * then the window will be updated.
- */
-
- void ewindow_open(ewindow);
- /* Opens the window (at the top of the window stack).
- */
-
- void ewindow_update(ewindow);
- /* If the picture changes, call this to redraw the picture.
- * If the window is sharing a drawing cache with multitasking pictures then
- * the update may not occur immediately - you can use 'ewindow_updatecomplete'
- * to check that it has occured.
- * (N.B. Wimp redraws are handled automatically).
- */
-
- void ewindow_close(ewindow);
- /* Closes the window.
- * Sprite memory is released if the window is using it.
- */
-
- void ewindow_destroy(ewindow);
- /* Closes the window and destroys the window structure
- */
-
- wimp_w ewindow_handle(ewindow);
- /* Returns the wimp window handle so that you can do low-level things (such as
- * attaching menus).
- * Be careful what you do with the window, some things may caused undefined behaviour.
- * Especially, don't alter the work area, and use the functions given for things like
- * opening, closing or deleting the window.
- *
- * I am likely to add routines to this module that allow manipulation of the window
- * i.e. changing its work area, position and size. If you want anything in particular
- * included then contact me (contact points are in the !ReadMe file).
- */
- #endif
-