# KeyWatch Module Functional Specification

CONFIDENTIAL

Document ref: | 1215,501/FS
Project: | ICA-3
Revision: | $Revision$
Date: | $Date$
Author(s): | Simon Middleton
Change: | *** LIVE ***
Classification: | Acorn Confidential

## Contents

1.0 | Overview
2.0 | Outstanding issues
3.0 | Technical background
4.0 | User interface
5.0 | Programmer interface
6.0 | Data interchange
7.0 | Data formats
8.0 | External dependencies
9.0 | Acceptance test
10.0 | Non compliances
11.0 | Development test strategy
12.0 | Product organisation
13.0 | Future enhancements
14.0 | Glossary
15.0 | References
16.0 | History

## 1.0 Overview

There is a need amongst a number of applications (eg ICA, Java) to be able to capture all the users key-presses individually, rather than in the transformed form given by the Wimp. This module provides access to all these events in formats suitable for the applications currently requiring them.

The goals of this module are

1. It should be as simple as possible
2. It should sit on top of existing interfaces and not require any changes to other modules (eg Wimp, Kernel etc.)
3. It should work on RISC OS 3.1
4. It should not introduce any significant extra problems to any future work to upgrade the RISC OS input system.

To cut down on module proliferation this is an extension of the KeyWatch module originally created for the NC100. This module (in version 0.01) originally only implemented the first two SWI calls.

## 2.0 Outstanding issues

None known.

## 3.0 Technical background

The module accomplishes its task by looking at the events generated

1. when a key is pressed or released
2. when a key is entered into the keyboard input buffer.

On KeyV the kernel first calls EventV to pass the key up or down event and then processes the key through the international keyboard handler and, if necessary, inserts the key into the keyboard buffer. After a suitable interval if the key is still held down then it inserts the key in the keyboard buffer again.

All this information is combined to generate a new key event stream containing all the extended data required.

The characters inserted into the keyboard buffer by the keyboard driver are removed by the KeyWatch module therefore an application using this interface will not receive any keys through the usual wimp key event interface.

## 4.0 User interface

There is no user interface.

## 5.0 Programmer interface

### SWI KeyWatch_Register (+00)

    IN:
    	R0 = flags
    		bits 0-31: reserved
    OUT:
    	R0 = Address of PollWord

Register with the module to have a pollword updated.

### SWI KeyWatch_Unregister (+01)

    IN:
    	R0 = Address of PollWord

    OUT:

Unregister a previously allocated pollword.

### SWI KeyWatch_Version (+02)

    IN:
    	R0 = flags
    		bits 0-31: reserved
    OUT:
    	R0 = feature flags
    	R1 = major version * 100
    	R2 -> minor version string

Return version and feature information about the module.

### SWI KeyWatch_RegisterScan (+03)

    IN:
    	R0 = flags
    		bit 0:  1 = store codes as PS/2 scan codes
    			0 = store codes as Acorn internal scan codes
    		bit 1:  1 = send code as message
    			0 = store code in buffer
    		bit 2:  1 = include mouse clicks
    			0 = ignore mouse clicks
    		bit 3:  1 = store key transition events (scan codes)
    			0 = ignore transitions
    		bit 4:  1 = store buffer events
    			0 = ignore buffer events
    		bit 5:  1 = remove code from input buffer
    			0 = leave code in input buffer
    		bits 5-31: reserved

    	R1 = wimp task handle
    OUT:

Call this after receiving input focus to change from using KeyEvent to NewKeyEvent. Note that there may be characters in the input buffer before this is called. These will be delivered to the application as normal through the wimp key event. If possible these should be processed to avoid losing any key presses.

Note that even if scan codes are not entered in to the poll buffer then scan code processing is still performed which means that the shift state is accurate and the scan code is still stored with the buffer code.

If bit 5 is set then OS_Byte,145 is used to remove the key code from the buffer. This prevents the key press from also appearing via the Wimp key event or similar.

### SWI KeyWatch_DeregisterScan (+04)

    IN:
    	R0 = flags
    		bits 0-31: reserved

    	R1 = wimp task handle
    OUT:

Call this after losing input focus or on window close to allow another window to set its mode correctly.

If the application requested that key events were buffered then there may be keys left in the buffer. Therefore in this case the task should read any keys out using KeyWatch_Poll and send them back to the wimp using Wimp_ProcessKey so that they are sent on to the task receiving the input focus. This must be done before calling Deregister.

Similarly if the application had requested that the keys were delivered using messages then it should maintain a flag to say whether it currently owns the input focus and should call Wimp_ProcessKey for any messages received when it doesn't.

### SWI KeyWatch_Poll (+05)

    IN:
    	R0 = flags
    		bits 0-31: reserved
    	R1 = wimp task handle
    	R2 = address of buffer or null
    	R3 = size of buffer
    	R4 = max number of entries to retrieve
    OUT:
    	R0 = flags out
    		bit 0: 1 = an overflow occurred on the internal buffer
    		bits 1-31: reserved
    	R1 = number of bytes per entry

    	if R2 = NULL then
    	  R2 = NULL
    	  R3 = size of buffer needed for all entries
    	  R4 = number of entries pending
            if R2 <> NULL then
    	  R2 = byte after last buffer byte filled
    	  R3 = size left in buffer
    	  R4 = number of entries asked for and not retrieved

The given buffer is filled with the pending data in the same format as the message data shown below. ie currently there are three words of data in the order flags, scan code, key code.

The flags in R1 are sticky and are cleared when some of the data is read from the buffer. R2 and R3 are updated with their new values after writing out the event structures. R4 contains the size of an individual structure (currently 12 bytes).

If the buffer address is given as null and the size of the buffer as zero then no data is written and R3 on exit will have been decremented by the size of the data that would have been written.

### SWI KeyWatch_Ignore (+06)

    IN:
    	R0 = flags
    		bits 0-31: reserved
    OUT:

The SWI is allows other modules to instruct the KeyWatch module to ignore the next key that is pressed. This allows modules such as the STB IR handset module to by-pass the KeyWatch module.

### Command `*KeyWatchForceClose`

This command forces keywatch to discard all registrations and detach from all event handlers. This means that it can be killed. It is only designed to be used if a client application crashes so that the module can be killed safely.

## 6.0 Data interchange

The following message is sent when a key event is generated by the module (if the appopriate flag was set on registering).

### Message_KeyEvent (tbd)

+0 | size (36)
+16 | message code (tbd)
+20 | flags
bit 0: 1 = Scan code is valid, 0 = Scan code is invalid
bit 1: 1 = Key code is valid, 0 = Key code should be ignored
bit 2: 1 = Key going up, 0 = Key going down
bit 3: 1 = this key code was preceded by a nul character in the keyboard buffer
bit 4: 1 = this scan code was preceded by an 0xE0 character in the keyboard buffer
bits 5-15: reserved
bit 16: 1 = Left Shift is down, 0 = Left Shift is up
bit 17: 1 = Right Shift is down, 0 = Right Shift is up
bit 18: 1 = Left Ctrl is down, 0 = Left Ctrl is up
bit 19: 1 = Right Ctrl is down, 0 = Right Ctrl is up
bit 20: 1 = Left Alt is down, 0 = Left Alt is up
bit 21: 1 = Right Alt is down, 0 = Right Alt is up
bits 22-31: reserved
+24 | scan code
either PS/2 or EventV codes
+28 | key code
As inserted into keyboard buffer

When a key code is event structure is created the scan code of the last key to go down is added to it. This only happens on the first key code received after the key goes down. Therefore an auto-repeat key can be distringuished by the fact that the scan code field is invalid.

Note for PS/2 codes the entire byte sequence is entered into the buffer. The Windows keys currently generate 0x7E (left) and 0x7F (right) until the correct codes can be ascertained. Up to and including version 0.08 of this module the codes generated were extended codes (i.e. 0xE0 was generated before each one). From 0.09 this was changed.

## 7.0 Data formats

No new data formats are defined.

## 8.0 External dependencies

None.

## 9.0 Acceptance test

The module will work on RISC OS 3.1 upwards.

## 10.0 Non compliances

None.

## 11.0 Development test strategy

To be decided.

## 12.0 Product organisation

A module written in C.

## 13.0 Future enhancements

Optionally assemble the bytes of a UTF8 sequence into a UCS4 code.

## 14.0 Glossary

N/A.

## 15.0 References

N/A.

## 16.0 History

    $Log$
    Revision 1.2  1998/10/07 18:44:03  smiddle
    Moved to trunk.
    Changed the fake Windows keys from extended to plain in the PS/2
    mappings. This stops strange results being seen in the ICAClient.
    You must use ICAClient 0.33 or later with it now though.

    Version 0.09. Tagged as 'KeyWatch-0_09'

    Revision 1.1.2.7  1998/09/28 16:46:52  olove
    Added a new SWI KeyWatch_Ignore which will ignore the next key press received by KeyWatch.

    Revision 1.1.2.6  1998/06/05 13:57:39  smiddle
    Added the Windows Menu key and fake versions of the left and right Windows keys.
    Added a flag to say that a byte was preceded by the PS/2 E0 extension byte.

    Version 0.07, 1.1.2.9. Tagged as 'KeyWatch-0_07-1_1_2_9'

    Revision 1.1.2.5  1998/03/20 14:55:12  smiddle
    Added KeyWatchForceClose command to clean up if a client crashes.

    Version 0.05, 1.1.2.7. Tagged as 'KeyWatch-0_05-1_1_2_7'

    Revision 1.1.2.4  1998/02/09 11:02:08  smiddle
    Changed KeyWatch_Poll API to stop allow swallowing of buffer codes even when only using
    scan code events.

    Version 0.04, 1.1.2.5. Tagged as 'KeyWatch-0_04-1_1_2_5'

    Revision 1.1.2.3  1998/02/06 17:00:31  smiddle
    Fixed some of the PS/2 codes. Changed mechanism so that the real PS/2 style
    code stream is output.

    Version 0.03, 1.1.2.4. Tagged as 'KeyWatch-0_03-1_1_2_4'

    Revision 1.1.2.2  1998/02/03 18:09:57  smiddle
    Rejigged how PS/2 codes are handled and added a few more flags to RegisterScan

    Version 0.03, 1.1.2.3. Tagged as 'KeyWatch-0_03-1_1_2_3'

    Revision 1.1.2.1  1998/02/03 15:25:19  smiddle
    Whole new load of functionality to support getting a stream of scan keys.
    See doc/keywatch.html for details.

    Version 0.02, 1.1.2.2. Tagged as 'KeyWatch-0_02-1_1_2_2'

This document is issued under license and must not be copied, reproduced or disclosed in part or whole outside the terms of the license. | © Acorn Computers Ltd 1997

Last modified: Wed Oct 7 19:45:24 BST 1998