[Jaffa Software]

WimpWorks Extension Modules

Introduction

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 !WimpWorks.Resources.WEMs.

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)

!Run

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

!RunImage

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 be added, uk_gfx which should redraw any unknown graphics objects.

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: &10 - FontWEM
&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 PROC or FN, eg. OPENWINDOW(main) would be called as PROCopenwindow(main) and TASKINFO(&01) as FNtaskinfo(&01).

!Sprites

As with !Run this file is technically optional, however should be defined so that your WEM appears with an attractive icon.

Desc

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 jaffa_event 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 return%=FNjaffa_event(...).

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 defined in FNname_init, eg. myEvnt%=FNencode("Mode 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 ENDHELP command, followed by zero or more other command definitions.