
 DeepKeys 2.06 (23-Jul-2003)  Cerilica 2003
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 DeepKeys has two functions, it implements a word-deep rather than byte-deep
 keyboard buffer, and it extends the Wimp KeyPress message with modifiers and
 physical key number.
 
 DeepKeys can be distributed with any program, PD or commercial, providing that
 this documentation is included intact, and that the following credit is
 reproduced in any other documentation, manuals and/or help files:
 
    DeepKeys  Cerilica Ltd 1999-2003  Contact: <simon@cerilica.com>


 Keyboard Buffer
 ~~~~~~~~~~~~~~~
 DeepKeys implements a word-sized keyboard buffer. Consequently all system
 calls that deal with the keyboard buffer now input and output word-sized
 values. "Deep" key ranges are allocated by Alan Glover at Pineapple Software
 <allocate@pinesoft.demon.co.uk>.
 
 InsV, RemV and CnpV handle word-sized keypress codes, but block mode is still
 byte-orientated. OS_Byte 138,0,<code> can take "deep" key codes, and OS_ReadC
 returns word-sized values.

 As of 2.06, InsV and RemV (in "byte" mode) can additionally insert, remove or
 inspect the modifier state in R3, in the format below, by setting R1b30 on
 entry. This bit will be CLEAR on exit if DeepKeys 2.06+ is present (if set on
 exit, the module is not available and the call has failed due to the buffer
 number being out of range). If a keypress is removed by the normal RemV call,
 the associated modifers will be returned by the wimp filter, as below. Please
 note that this does not extend to OS_Byte,138, as registers>R2 might have
 been corrupted by ByteV claimants.
 

 KeyPress Poll Event
 ~~~~~~~~~~~~~~~~~~~
 DeepKeys installs a wimp filter which extends the normal keypress event. Poll
 reason 8 returns a word-sized keypress code at block+24 as normal, but this is
 followed by a new information word at block+28 containing the state of the
 modifier keys at the time the keypress was detected, plus the physical key
 number of the non-modifier key generating the keypress:
 
  +24 KeyPress code (word)
  +28 DeepKey information:
      b0 Left Shift    b1 Right Shift
      b2 Left Ctrl     b3 Right Ctrl
      b4 Left Alt      b5 Right Alt
      b6 Left Logo     b7 Right Logo
      b8 Menu key
      b9-14 reserved (0)
      b15 Always 0
      b16-31 Physical key number (16 bit for future expansion)


 Programming
 ~~~~~~~~~~~
 If an application requires DeepKeys, it should RMEnsure it. DeepKeys has been
 allocated the common installation point of "<Boot$ToBeLoaded>.!!DeepKeys"
 (note double pling).
 
 If an application wants to make use of DeepKeys if available, but does not
 require it, DeepKey's presence can be detected by setting bit 15 of block+28
 before calling Wimp_Poll or Wimp_PollIdle - this bit is guaranteed to be clear
 in a Key Pressed Event if the DeepKeys information word is present.
 
 Most keyboards generate key codes for the Logo and Menu keys (Cerilica's MMK
 certainly does), but DeepKeys also treats them as modifiers, so an individual
 application can use combinations such as Logo-A just as if it were Ctrl-A.
 When operating like this, the code generated by the initial Logo or Menu
 keypress must be ignored (but not passed on). The key code returned will be of
 the unmodified keypress, but the Logo or Menu modifier will be flagged in the
 extension word.
 
 The physical key number can be used to assign different actions to sets of
 keys that generate the same keypress code - Return and Enter for example.
 When implementing such a scheme, make sure that the DEFAULT action is that
 assigned to the more-common keypress, eg:
 
   CASE block!24 OF
     WHEN 13:REM Return, Enter or Ctrl-M
       CASE (block!28)>>>16 OF
         WHEN &67: PROCkeypress_ENTER
         WHEN &54: PROCkeypress_CTRL_M
         OTHERWISE:PROCkeypress_RETURN
       ENCASE
 
 This ensures sensible operation with future keyboards, and with keypresses
 not generated by the keyboard - see following section. Please note that to
 allow the Logo and Menu keys to act as modifiers, they do not return a valid
 physical key number when pressed in isolation.
 
 Problems
 ~~~~~~~~
 RemV block mode cannot sensibly be used - word values in the buffer will be
 truncated to their lowest eight bits.
 
 Key codes inserted into the buffer by software, rather than by the keyboard,
 do not normally have modifier or physical keys associated with them (unless
 the new InsV call is used). When delivered to a Wimp program it will report
 the state of the keyboard modifiers at the time of the simulated keypress, and
 the physical key number of the last REAL keypress. This physical key number
 will NOT match the key code inserted. This is why Wimp applications must be
 careful about interpreting the physical key number, as described above.
 
 The DeepKeys module does not pass keyboard buffer events on to existing
 claimants of the InsV, RemV and CnpV vectors, and so must be loaded first to
 avoid disabling some utilities - hence the allocated install position
 "<Boot$ToBeLoaded>.!!DeepKeys". This is a consequence of the way these vectors
 are used, and cannot be avoided without vector claimant prioritisation, as
 performed by Cerilica's VectorExtend module.


 DeepKeys is copyright Cerilica Limited and was written by Simon Birtwistle.
 <http://www.cerilica.com/>                      <mailto:simon@cerilica.com>

