CONFIDENTIAL
Document ref: | 1215,501/FS |
Project: | ICA-3 |
Revision: | $Revision$ |
Date: | $Date$ |
Author(s): | Simon Middleton |
Change: | *** LIVE *** |
Classification: | Acorn Confidential |
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 |
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
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.
None known.
The module accomplishes its task by looking at the events generated
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.
There is no user interface.
IN: R0 = flags bits 0-31: reserved OUT: R0 = Address of PollWord
Register with the module to have a pollword updated.
IN: R0 = Address of PollWord OUT:
Unregister a previously allocated pollword.
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.
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.
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.
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.
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.
*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.
The following message is sent when a key event is generated by the module (if the appopriate flag was set on registering).
+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.
No new data formats are defined.
None.
The module will work on RISC OS 3.1 upwards.
None.
To be decided.
A module written in C.
Optionally assemble the bytes of a UTF8 sequence into a UCS4 code.
N/A.
N/A.
$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 |