C the WIMP 7

The reason why (1)

Last time, I covered the wimp_poll in a very basic way without really saying very much about the reason codes. I will be covering the codes in stages rather than all at once as they will tie in as the series continues. For this tutorial, reason codes 0 to 5 will be covered.

Recap

_swi (Wimp_Poll,_INR(0,1)|_OUT(0),mask,mem_block,&reason);

where mem_block is a pointer to a memory location containing a structure for the wimp poll and reason is an int returned by the swi.

Reason code 0 - NULL reason code

This code is returned when the WIMP has not detected anything happening for the registered application. There are many hundreds of these returned during an application being loaded (how many tasks to you have on the iconbar which are just "sitting there" idle?). If the WIMP was to acknowledge via the application if reason code 0 was returned, the machine would slow, perhaps not a great deal, but given enough applications doing this, would slow noticabley.

For this reason, this code is normally masked out (bit 0 in the wimp_poll mask).

Reason code 1 - Redraw window request

If you generate a window with something on it (could be text, a picture, a series of icons) and (say) you pull another window over it or click on the mouse menu button to obscure part of whatever is on the window, then when these obstructions are removed the window will need to be redrawn. If the window is not redrawn, whatever had been obscured will be blanked on that window. When this reason is called on, the caller has to pass over the window handle of the window to be redrawn.

Assuming that you have used the method I have employed in previous issues, this would take the form

case 1 : redraw_window(wb);

The method employed for redrawing a window will be dealt with at a later date.

Reason code 2 - Open window request

As the name implies, this is a request by the user to open a window. This can be any window from any part of the application.

When used as part of the poll routine, the window handle of the requested window should be passed in the same way as for a redraw window request - by specifying the base of the wimp block.

If the window operation results in the window not having any new parts, the wimp will re-open the window by itself. However, if part of it had been obscured the wimp will look at the window flag 4 (window can be drawn completely by the wimp). If it is set, then no user intervention is required to update the window. If this flag is unset (the window contains something which cannot be generated by the wimp itself such as text or graphics), the wimp returns reason code 1 (redraw request)

Reason code 3 - close window request

This code means that the user has asked for a particular window to be closed.As with reason codes 1 and 2, the calling routine should specify the base of the poll block.

Reason code 4 - pointer leaving window

This reason has been returned when the pointer has, for whatever reason, found itself outside of the window, or no longer directly over the window (for example, a menu has been opened and the pointer is now over this and not the window).

If the window is deleted, this reason code will not be received.

The window handle of the window the pointer has left will be returned into the poll block when this reason is received.

Reason code 5 - pointer entering a window

This is the opposite of reason code 4. The pointer has found itself over a window due to a menu it was currently on being close, a window obscuring the window we're interested in being closed or the user has moved the mouse over onto the interested window.

The window handle of the window the pointer is now over will be returned into the poll block when this reason is received.

These final 2 reason codes are rarely used as the wimp will normally return the window handle when the mouse clicks on a window or icon (or if a key is pressed). It is of use though if you need to change the pointer shape over a particular area of a window, or indeed, over a window.

Okay, that's the first 6 reason codes explained.

These are the simplest of the reason codes and allow us to start constructing a WIMP application.

But what if I don't want to acknowledge any of these reason codes?

As stated when I covered the Wimp_Poll swi, these values can be masked out. A simple way to do this can be carried out as follows :

If you know which reason codes you wish to ignore, open a task window (press CTRL F12) and type at the * prompt BASIC.

Suppose we want to mask reasons 0, 4 and 5, then at the > prompt type

PRINT 1+(1<<4)+(1<<5)

This should return a value of 49. The line actually means to print the value of 1 (=bit 0, NULL) + 1 shifted left 4 places (=bit 4, pointer leaving window) + 1 shifted left 5 places (= bit 5, pointer entering window). The brackets are required for prescendece (try typing the line in without the brackets, the machine returns 64 followed by unknown or missing variable)

This value is entered as r0 in the swi call :

(BASIC)

SYS "Wimp_Poll",49,mem_block% TO reason%

(C)

_swi(Wimp_Poll,_INR(0,1)|_OUT(0),49,mem_block,&reason);

As a simple task for next time, construct a small single tasking application which returns the mask.

Remember that reasons 14 - 16 are reserved (i.e. must be 0). Next time, we'll look at reason codes 6 to 12.

paulf.johnson@ukonline.co.uk