WimpWorks Extension Modules
WimpWorks Extension Modules (WEMs) are application directories which contain software plugins which can be compiled into a WimpWorks application. This document describes how to produce plug-in WEMs for WimpWorks.
These components are written in standard BBC BASIC (and can take advantage of any WimpWorks commands present - even in other WEMs) and add new commands and/or events to WimpWorks applications to take advantage of new ideas, protocols or to simply add a command which is felt is needed.
WEMs are installed by copying them into
Format of a WEM
A WEM consists of (at least) four files inside an application (a directory beginning with an exclamation mark - '!').
The files are listed below and will then be explained in detail:
- !Run (Obey)
- !RunImage (BASIC)
- !Sprites (Sprite)
- Desc (Text)
This file is technically optional, however it should be present so that if the WEM is double clicked in a directory display (accidentally or on purpose) the user does not get an error message.
It is recommended that the file starts WimpWorks if it can, otherwise simply do nothing:
| !Run file for !Test, a WWv2 WEM | © Jaffa Software 1998. All rights reserved. IconSprites <Obey$Dir>.!Sprites If "<WimpWorks$Dir>"<>"" Then Run <WimpWorks$Dir>.!Run %*0
This file is the BASIC file which will be linked into the WimpWorks application if the WEM is chosen to be included. This file has a relatively rigidly defined structure which must be adhered to. It also contains the actual code of all the new WimpWorks commands.
The file contains, in addition to the code for any new commands, four functions which must be present, all are prefixed with the name of the WEM (see later) and must all return zero (0).
As of v2.20 and above, there is an additional function which should
uk_gfx which should redraw any unknown graphics
In a WEM named
test the functions would be:
- FNtest_init - Called when the application is run, and guaranteed to be called exactly once.
- FNtest_pre(wimp%, action%) - Called before the WimpWorks
core library processes the Wimp_Poll call.
wimp%is a pointer to the 256-byte block passed in R1 to Wimp_Poll.
action%is a pointer to the reason code returned in R0 and can be accessed with
!action%. These pointers allow you to modify the appearance of Wimp_Poll to WimpWorks.
- FNtest_post(wimp%, action%) - Similar to
..._pre, however is called after the WimpWorks core library has processed the event.
- FNtest_exit - Called when the application is about to exit. This is called before Wimp_CloseDown and should be used to close any files opened etc.
- FNtest_uk_gfx(object%, screen%, sx%, sy%, window%, bbox%) -
Called when an unknown graphics object is needed to be redrawn.
The "fudge factors" can be added directly to
window coordinates (eg. 100, -100) to get an absolute position
on the screen; taking into account scroll bars and window position.
object%- Pointer to the object (see CREATEGFXOBJECT)
screen%- Pointer to the bounding box on screen
sx%- Horizontal fudge factor
sy%- Vertical fudge factor
window%- The window being redrawn
bbox%- Bounding box of rectangle being redrawn
If you are writing a WEM which uses CREATEGFXOBJECT, REMOVEGFXOBJECT and _uk_gfx() then you will need a new ObjectID, the following ranges are defined:
|&00 - &0F||Reserved for internal use by Jaffa Software|
|&10 - &7F||Allocated by Jaffa Software for new WEMs etc. If you would like an
id in this range, please contact us.
The following ObjectIDs have been allocated:
|&80 - &FF||Freely usable by anyone, for anything, but should not be used in a released product.|
There is also a stub routine which can be REDEFINEd to point to your own redraw routine, note the original should still be called, otherwise the internal graphics objects will not be redrawn.
DEF PROC__redraw_internal(temp%, sx%, sy%, window%, bbox%) ' temp% - &100 byte block for temporary use ' sx% - Horizontal scroll offset ' sy% - Vertical scroll offset ' window% - Window being redrawn ' bbox% - Bounding box being redrawn ' This routine is called within the Wimp_RedrawWindow ' loop and so should not call that itself. ENDPROC
The rest of the file is left to zero or more procedures and/or
functions which define the code for any new WimpWorks commands. Any
WimpWorks command (whether core or provided by another WEM (which must
also be included)) can be called, however they must be called in lowercase
and prefixed with either
OPENWINDOW(main) would be called as
As with !Run this file is technically optional, however should be defined so that your WEM appears with an attractive icon.
This text file instructs WimpWorks how to process the WEM, data is
held within a
DEF WEMname...ENDWEM structure and
anything outside such a structure is ignored.
The various WEM structures which must be implemented are:
DEF WEMdetails Name test Description Test WEM Author (c) Jaffa Software 1998 Version 1.00 (21-Feb-1998) Type 2 ENDWEM
- Name - Used for prefix in the functions above
- Description - A more verbose description used in the "WEMs to include" menu
- Author - An author and copyright string as found in "About this program" boxes
- Version - A version string as also found in "About this program" boxes
- Type - This should be two in all third-party WEMs, other values are reserved for future expansion
DEF WEMevents Mode changed VAL(eva$), VAL(evb$) old_mode%, new_mode% Writable clicked VAL(eva$), VAL(evb$), evc$ window%, icon%, text$ ENDWEM
Each new event consists of three lines: the first contains the name of the
event (as it should be included in the "Respond to" menu (events
expecting a value to be returned should have
(FN) as the last four
characters on this line)). The second line is the decode string, this
is used to convert the three string paramets passed to
into non-string values if necessary. The final line is the default parameter
set which is appended to the definition of a subroutine when it is associated
with the event.
Events which are unattached always return
TRUE (-1). To initiate
an event call
PROCjaffa_event(event, eva$, evb$, evc$) or
event is an integer representation of the event and is the result
returned from ENCODE when applied to the name of the event. This could be
changed") or calculated using !EncodeStr.
DEF WEMinclude RMEnsure ColourPicker 0.30 RMLoad System:Modules.ColourPicker ENDWEM
This section will include the one line in the block in the !Run file of the application if this WEM is included. The above line would be used in a WEM providing support for the ColourPicker module.
DEF WEMcommands BEEP PROC <length> Make a beep for <length> seconds, this is a command which is a bit silly. ENDHELP BOOLEAN FN Returns a random boolean value (TRUE or FALSE). ENDHELP ENDWEM
Within this block is a list of the commands added, followed by an amount of whitespace and their type: PROC or FN. Following this is the syntax line which is appended to the command in the online help window. The syntax line must be blank if there are no parameters.
Finally, there is a block of text defining the online help itself for the
command, this is practically unlimited, but the TRIMmed length of the line
should be <= 45 characters, so that it can fit into the width of the online
help window. After the text is defined, there is an
command, followed by zero or more other command definitions.