C the WIMP

Last time, I covered reason codes 0 to 5 and set you a small task to write a utility to return the reason code mask. My solution is on this months cover disc.

Okay. Reason codes.

Reason code 6 : mouse clicks.

If you click on the mouse over a window belonging to your application, the poll routine returns reason code 6, with an associated block of information. If you consider wimp_block.h, you will see in there the structure this is placed into.

typedef struct mouse {
                      int mouse_x;
                      int mouse_y;
                      int buttons;
                      int window_handle;
                      int icon_handle;
                     } mouse;

where buttons corresponds to the mouse button pressed (generally, this is 1 for adjust, 2 for menu and 4 for select) and icon_handle can be either the icon it is over or -1 for the work area background. window_handle is either the window handle, -1 for the background or -2 for the iconbar.

mouse_x and mouse_y are given as the absolute screen co-ordinates, rather than the relative ones.

Fun and games ensue though when you consider the values buttons can return.

Depending on if you are dragging or just clicking, you will obtain different results. Depending on how you have set up the action flags word (see back to C the WIMP 5) on a window definition will depend on the values the mouse click will return.

Window work area flags

0. Ignore all clicks
1. Notify the task continually while the mouse is over the work area
2. Click notifies task (auto - repeat)
3. Click notifies task (once)
4. Release over work area notifies the task
5. Double click notifies task
6. As (3) but can also drag (returns button state * 16)
7. As (4) but can also drag (returns button state * 16)
8. As (5) but can also drag (returns button state * 16)

The window handle is also returned in the structure - this is essential for programs running more than one window (imagine if it didn't - the poor program would not know which window you were talking about!)

Reason 7 : User drag boxes

(This will be more fully covered in a later tutorial). In a nutshell, this reason is returned when the user drags a 'draggable' icon (such as when you save a file to a disc, the icon is defined as draggable - the reason code 7 is returned when the drag starts.

Reason 8 : Key presses.

This is only returned if the focus window (this is the window with the caret in, or has (normally) a yellow title bar - to gain focus, it is normally just a case of clicking on the desired window) or has the hot keys flag set.

As with the mouse click, when a key press is registered, a block of information is passed back from the poll call.

Key pressed structure (from wimp_block.h)

typedef struct key {
                    int window_handle;
                    int icon_handle;
                    int x_offset;
                    int y_offset;
                    int caret_n_flags;
                    int index_of_caret;
                    int code;
                   } key;

From x_offset to index_of_caret allow us to determine where the caret is when the key is pressed.

An important thing to bear in mind is that many applications may have writable icons. If your desktop has multiple windows up (which they invariably do), the current active window will have the input focus. It therefore does not follow that just because our window has a writable icon in, that our application will be given the chance to respond to the key press. The window has to have the focus in for the application to have this reason code returned. A simple test is this. Open a couple of windows with a text editor (such as Zap, StrongED or Edit), we shall call the last one opened our program window.

Click on one of the window and type "hello". Move the mouse to the next and type something else. Carry on until you get to our program window. In this window type "our window". Move the mouse to any of the other windows and click on a mouse button. Now press F3 - it is the window you have just clicked on which will have responded to the key event.

A second point to remember is that as RISC OS uses a full character set (including characters 128 to 255, the so-called "top bit set"), that it is unable to return function keys and other special keys (such as the arrow buttons) as a single byte value. To do so would give the OS a headache. Instead, a double byte value is returned with the high bit set to 1 (the upshot is all the results start past &100 - see below for a list of these keys)

Values returned for the special keys. All values are expressed in hexadecimal.

The final important note is that when using reason code 8 must respond to all keys - even if they are not being recognised by your application or (for some reason) you wish to ignore. This has to be done so other applications are given a chance to respond. A good example of this is to press F12.

This will always (when using the desktop) return you to the CLI prompt (*). If a task intercepts key presses but doesn't pass on unrecognised key presses, then F12 will have no effect as long as it is in a position to respond to this reason code.

Reason code 9 : Menu selection.

This is returned when a selection is made on a menu. Again, it returns from the poll with a block defined. I will return to this topic when I cover menus.

I cannot see a real benefit in going through the remaining 8 reason codes (okay, there are actually 10, but reasons 14 - 16 are reserved) other than to say that there are more reason codes, but they will be dealt with at a later stage.

Next time, we will use the knowledge from this and the past issue and start putting them to some use. In the mean time by looking at the listings for part1b.c and part2a.c, can you add to this to intercept a mouse click and via the error box, tell which mouse button has been clicked. If you have only just started to subscribe to Archive and don't have these listings, they are available from here (as are the other tutorials already published) or as a back issue from Archive Publications themselves.