MASTERING THE WIMP

by Lee Calcraft

PART 2: CREATING WINDOWS

Last month we took a brief overview of the Wimp system, and a simple multi-tasking demonstration program was supplied. As promised, we return to explore this program in some detail.

First of all, if you experimented with the program as suggested, did you spot the inconsistency mentioned last month? It has to do with the way in which the window is updated. The window displays the time and date, but this is only renewed when the Wimp asks the task to redraw the window. If you move the window around the screen, the displayed time remains the same, and is only brought up to date when the window is scrolled, or when part of the window is uncovered.

A small alteration to the program permits the full Wimp palette to be displayed.

This illustrates the degree to which the Wimp handles all routine activities without the need for intervention by the user's program. The Wimp only calls for help when it cannot get by unaided. As mentioned last month, such activities are handled by the so-called "Wimp_Poll" call, which forms an anchor point for the dialogue between the Wimp and each concurrent task (the terms task and program are largely synonymous in the context of this series).

We shall treat the "Wimp_Poll" routines in a future issue. This month we will concern ourselves with two of the calls which are normally made before calling SYS "Wimp_Poll".

INITIALISING THE WIMP

The first of these, SYS "Wimp_Initialise", is an easy one. Its function is to tell the Wimp of the existence of the new task, and to allow the Wimp to assign a task handle (a unique number which will be used to identify the task in certain future operations), and to inform the task of the version number of the Window Manager module installed in the computer.

Figure 1. SWI "Wimp_Initialise" (SWI &400C0)

On Entry
R0=Last Wimp ver no *100 (at least 200)
R1="TASK" (low byte="T", high byte="K")
R2=Pointer to description of task

On Exit
R0=Current Wimp version number *100R1=Task handle

Lines 150 and 160 of last month's program are all that is needed for this call. The first stores the word "TASK" (literally) at location block%, while the second performs the call itself. See figure 1 for details of the parameters passed by this call, and the article "SYS Calls Explained" in last month's RISC User if you are unfamiliar with SYS calls. R0 is given the value 200 (the latest version of the Window Manager), R1 holds the word "TASK" (literally), while the third parameter supplies a brief description of the task for the Task Manager display. On exit the variables version% and task% will hold respectively the version number of the Window Manager, and the task handle which it has assigned to the task.

The parameter supplied to R1 by the user is a little unusual in that it is not a pointer to a text string, but the text string itself. It has the value &4B534154. Acorn have devised this little ruse to enable the RISC OS Window Manager to identify RISC OS tasks. Programs written for use with the Arthur Wimp were not required to supply any parameters with SYS "Wimp_Initialise", and it would therefore be very unlikely that an Arthur "Wimp_Initialise" would be made with the value &4B534154 in register R1.

CREATING A WINDOW

The second call which a task must make is to "Wimp_CreateWindow". This call supplies the Wimp with a vast quantity of information about the window, including its size, colouring, whether it has scroll bars, what icons it contains and so on. Since there is far too much data for the available ARM registers, the information is supplied in a so-called parameter block, and the address of the block is itself passed as a parameter in register R1. On exit, the parameter block remains unchanged, but R0 contains the so-called window handle. This is a unique number assigned by the Wimp to this particular window, and will be used in further Wimp calls to identify it.

Figure 2. Parameter block for "Wimp_CreateWindow" SWI &400C1

0Visible Area min x coord
4Visible Area min y coord
8Visible Area max x coord
12Visible Area max y coord
16Scroll x offset rel to Work Area origin
20Scroll y offset rel to Work Area origin
24Handle to open window behind or
 -1=top -2=bottom
28Window flags
32Title foreground and frame colour
 (&FF=no frame)
33Title background colour
34Work Area foreground colour
35Work Area background colour
 (&FF=transparent)
36Scroll bar outer colour
37Scroll bar slider colour
38Title bcgnd colour when input focus
39Reserved (must be 0)
40Work Area min x coord
44Work Area min y coord
48Work Area max x coord
52Work Area max y coord
56Title bar icon flags
60Work Area flags
64Sprite area control block pointer
 (+1 for Wimp sprite area)
68Minimum width of window
70Minimum height of window
72Title data
84No of icons in initial definition
88Icon blocks (32 bytes each)

Figure 2 gives the contents of the parameter block for the call. To see how the call was used in last month's program, take a look at line 220. This sets the variable whandle% (the window handle) to the return value of FNcreate. This function serves to set up a parameter block for "Wimp_CreateWindow" and then makes a call to it. The function has six parameters. The first four are the x and y co-ordinates of the bottom left-hand corner of the visible part of the window (measured in standard graphics units), and the width and height of the visible part of the window. The last two parameters are the hidden parts of the window, and will only appear if the window is scrolled or extended in size - see figure 3.

Figure 3. Simplified relationship between the Visible Work Area and Work Area Extent

Figure 3

The function is defined in lines 510 to 770, and you will see that line 760 makes the SYS call to "Wimp_CreateWindow". The lines between 520 and 750 are concerned purely and simply with setting up the parameter block. To see how this works you will need to be familiar with the ?, ! and $ indirection operators. These are described in the short article "Indirection Operators Explained" elsewhere in this issue.

Line 520 just clears the 88 bytes of RAM from block% to block%+87. This is performed so that any parameters whose value is zero may be ignored (since zero values have been installed over the whole range). Lines 540-570 supply the four co-ordinates of the visible part of the window (bottom-left x, bottom-left y, top-right x, and top-right y respectively).

Similarly lines 690-720 supply the co-ordinates of the entire extent of the window. This area includes both visible and non-visible parts of the window, and is termed the Work Area. It should not be confused with the Visible Area (which is exactly what it says). To confuse the issue, Acorn have until recently used different terminology. The Visible Area was previously called the Visible Work Area; while the Work Area was previously called the Work Area Extent. We shall adhere to the most recent terminology.

In fact although the Visible Area is measured in standard graphics units from the bottom left hand corner of the screen, the Work Area co-ordinates are usually given relative to the top left-hand corner of the Visible Area. This makes the relationship between the two somewhat less than intuitive, and is compounded by the fact that the y co-ordinates of the Work Area are measured downwards. Because of this we will, for the moment at least, deal simply in terms of the six parameters supplied to the function FNcreate. To reiterate, these are the x and y co-ordinates of the bottom left-hand corner of the Visible Area, and its width and height, and the width and height of the non-visible part of the window (both of which could be zero).

Later in the series we will return to this question, and look in greater detail at the full relationship between the physical screen, the Visible Area and the Work Area.

WINDOW COLOURS

Lines 610-670 establish the colours of the various parts of the window. The values supplied are single-byte, and correspond to the standard Wimp palette (see figure 4). Generally speaking it is desirable to adhere to the colour numbers used in the program, in order to achieve conformity within the Desktop. But you might like to experiment a little, just to prove that this is not all fiction.

Figure 4. 16-Colour Wimp Palette

0-7Linear grey scale (white=0)
8Dark Blue12Cream
9Yellow13Dark Green
10Light Green14Orange
11Red15Light Blue

To display the whole palette, you could replace lines 980-990 in the program with the following:
980 FOR A=0 TO 15
985 SYS "Wimp_SetColour",A
990 CIRCLE FILL x0%+100,y0%-96-36*A,14
995 NEXT

Incidentally, when experimenting with Wimp programs such as this, it is generally much easier to test them outside the Desktop. To do this, simply run the program from memory (using RUN). When you have finished testing the program, click on the Close icon (X), and you will be left in Basic, with the program still in memory, all ready for further editing. If you are using the Desktop, the program must already be on disc, and when you quit, you cannot recover your program, and must re-load it from disc to edit or re-run it. Of course, you cannot test your program under multi-tasking conditions without the Desktop, but for many purposes, this is not important - especially since the Wimp sets up the appropriate mode, the Desktop background and standard Wimp colour palette when your program calls "Wimp_Initialise" from outside of the Desktop.

Next month we will complete our examination of "Wimp_CreateWindow", and a look at three important sets of flags: the Window flags, the Title bar icon flags, and the Work Area flags. In the meantime, you may like to experiment further with last month's program. Try for example setting a minimum height and width for the window (see figure 2).