C the Wimp

Part 5 : Let's make a start 2

Back in the second of this series, I put together a very simple WIMP program which did

nothing more than display an error box and be generally rather annoying.

While very simple, it did show how easy putting together a WIMP program really is.

From here on in, we will be expanding on the application listings (called c.part1a, c.part1b and c.part1c on the cover disc), but along with that, incoportating the libraries we have built up.

The first on our list of what to do is the definition of a window. Later on, we will see how this is done using a template file, but for now, we need to know how to create a window. The WIMP provides us with a simple method of doing this, the call Wimp_CreateWindow. This does require a parameter block (memory block) passed in.

The block looks like this

Wimp_CreateWindow block

Offset Controls

0 Visible area, minimum x

4 Visible area, minimum y

8 Visible area, maximum x

12 Visible area, maximum y

16 Scroll x offset

20 Scroll y offset

24 Handle to open windown behind

28 Window flags

32 Title foreground and frame

33 Title foreground

34 Workarea foreground

35 Workarea background

36 Scrollbar outer colour

37 Scrollbar inner colour

38 Title background when input focus claimed

39 Extra flags (OS 4+ only)

40 Work area, minimum x

44 Work area, minimum y

48 Work area, maximum x

52 Work area, maximum y

56 Titlebar icon flags

60 Workarea button flags

64 Sprite area control block pointer

68 Minimum width of window

70 Minimum height of window

72 Title data

84 Number of icons in initial definition (0 or more)

88 zero or more icon blocks, 32 bytes each.

An aspect of the window here needs to be defined - that is what is meant by the visible and work areas. It is also useful to consider the different parts to a window.

The visible area can be seen as not very large - which it isn't. Take for instance a draw file. If you set the paper size to be A1, without the zoom function, the work area is not visible completely on a normal monitor - only a proportion is. The same applies for any desktop application.

The RISC OS window is a simple affair, the above diagram shows this.

Given that we have a block to pass into the SWI, again, it is far simpler to define a structure to cover this (it is on the cover floppy, h.window). Again, it is included and a memory block allocated to it.

We need now to consider more fully some of the parameters in the block passed to Wimp_CreateWindow - they are not all just text or numbers.

Handle to open window behind

This can have 4 values

-1 top of the stack (window at the front of any others on the screen)

-2 bottom of the stack (behind all other windows)

-3 iconised (not visible)

x behind the window with handle x

Window flags

The window flag is a 32 bit number covering if the window can be dragged, is scrollable, can be closed and a variety of other fun things. Due to the number of flags, they are described on the cover disc (text file called wind_flags).

Extra flags byte (OS 4+ only)

If bit 0 is set, this gives the ability to use 24 bit colour in the titlebar validation.

Icon flags

Another 32 bit number, again described on the cover disc (icon_flags)

There is a program called !Toolkit on the comp.binaries/sources.acorn website which allows the rapid calculation of these two sets of values.

Title data

There are two methods of placing title data on a window, either as text or as a sprite.

The text can either be direct (max of 12 characters) or indirected (placed somewhere in memory, upto 255 characters). The same applies to sprites. These can either be from a sprite area (area of memory holding the sprites) or from the WIMP itself.

For the moment, we will consider the title text to be a simple 12 byte text file.

If you consider the following piece of code (from c.part2a), you can see how we assign memory to this structure and then assign values.

int create_window

(int x,int y,int width,int height,int extx,int exty,char *message)

{

int handle;

if ((window=malloc(sizeof(win)))==NULL)

{

report_error(1,"I can't create the window\0");

exit(1);

}

window->vis_min_x=x;

window->vis_min_y=y;

window->vis_max_x=x+width;

window->vis_max_y=y+height;

window->scroll_x=0;

window->scroll_y=0;

we then carry on filling the structure in a similar way and finally, we have the call.

Wimp_CreateWindow

in

r1	pointer to block containing the window definition

out

r0 window handle created.

The window handle is a number assigned by the WIMP to the window created.

This is not the end of the story. While we have created the window (and received back the window handle), we still have to physically create the window.

In listing c.part2a, this is performed using

void make_window (int whandle)

Here, we pass over the window handle into a parameter block and into two SWI calls, Wimp_GetWindowState and Wimp_OpenWindow.

Wimp_GetWindowState returns a block containing a shortened down version of the values passed to Wimp_CreateWindow while Wimp_OpenWindow does as the name implies.....

I would recommend that you have a look at the way this has been implemented and the

structures used.

Next time, I'll be padding out the poll routine and looking at a couple of events.