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


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