home *** CD-ROM | disk | FTP | other *** search
/ RISCWORLD 6 / RISCWORLD_VOL6.iso / Software / ISSUE5 / PD / rdpclient / DeepKeys_DeepK_Help < prev    next >
Encoding:
Text File  |  2004-05-16  |  5.3 KB  |  118 lines
  1.  
  2.  DeepKeys 2.06 (23-Jul-2003) © Cerilica 2003
  3.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  4.  
  5.  DeepKeys has two functions, it implements a word-deep rather than byte-deep
  6.  keyboard buffer, and it extends the Wimp KeyPress message with modifiers and
  7.  physical key number.
  8.  
  9.  DeepKeys can be distributed with any program, PD or commercial, providing that
  10.  this documentation is included intact, and that the following credit is
  11.  reproduced in any other documentation, manuals and/or help files:
  12.  
  13.     DeepKeys © Cerilica Ltd 1999-2003  Contact: <simon@cerilica.com>
  14.  
  15.  
  16.  Keyboard Buffer
  17.  ~~~~~~~~~~~~~~~
  18.  DeepKeys implements a word-sized keyboard buffer. Consequently all system
  19.  calls that deal with the keyboard buffer now input and output word-sized
  20.  values. "Deep" key ranges are allocated by Alan Glover at Pineapple Software
  21.  <allocate@pinesoft.demon.co.uk>.
  22.  
  23.  InsV, RemV and CnpV handle word-sized keypress codes, but block mode is still
  24.  byte-orientated. OS_Byte 138,0,<code> can take "deep" key codes, and OS_ReadC
  25.  returns word-sized values.
  26.  
  27.  As of 2.06, InsV and RemV (in "byte" mode) can additionally insert, remove or
  28.  inspect the modifier state in R3, in the format below, by setting R1b30 on
  29.  entry. This bit will be CLEAR on exit if DeepKeys 2.06+ is present (if set on
  30.  exit, the module is not available and the call has failed due to the buffer
  31.  number being out of range). If a keypress is removed by the normal RemV call,
  32.  the associated modifers will be returned by the wimp filter, as below. Please
  33.  note that this does not extend to OS_Byte,138, as registers>R2 might have
  34.  been corrupted by ByteV claimants.
  35.  
  36.  
  37.  KeyPress Poll Event
  38.  ~~~~~~~~~~~~~~~~~~~
  39.  DeepKeys installs a wimp filter which extends the normal keypress event. Poll
  40.  reason 8 returns a word-sized keypress code at block+24 as normal, but this is
  41.  followed by a new information word at block+28 containing the state of the
  42.  modifier keys at the time the keypress was detected, plus the physical key
  43.  number of the non-modifier key generating the keypress:
  44.  
  45.   +24 KeyPress code (word)
  46.   +28 DeepKey information:
  47.       b0 Left Shift    b1 Right Shift
  48.       b2 Left Ctrl     b3 Right Ctrl
  49.       b4 Left Alt      b5 Right Alt
  50.       b6 Left Logo     b7 Right Logo
  51.       b8 Menu key
  52.       b9-14 reserved (0)
  53.       b15 Always 0
  54.       b16-31 Physical key number (16 bit for future expansion)
  55.  
  56.  
  57.  Programming
  58.  ~~~~~~~~~~~
  59.  If an application requires DeepKeys, it should RMEnsure it. DeepKeys has been
  60.  allocated the common installation point of "<Boot$ToBeLoaded>.!!DeepKeys"
  61.  (note double pling).
  62.  
  63.  If an application wants to make use of DeepKeys if available, but does not
  64.  require it, DeepKey's presence can be detected by setting bit 15 of block+28
  65.  before calling Wimp_Poll or Wimp_PollIdle - this bit is guaranteed to be clear
  66.  in a Key Pressed Event if the DeepKeys information word is present.
  67.  
  68.  Most keyboards generate key codes for the Logo and Menu keys (Cerilica's MMK
  69.  certainly does), but DeepKeys also treats them as modifiers, so an individual
  70.  application can use combinations such as Logo-A just as if it were Ctrl-A.
  71.  When operating like this, the code generated by the initial Logo or Menu
  72.  keypress must be ignored (but not passed on). The key code returned will be of
  73.  the unmodified keypress, but the Logo or Menu modifier will be flagged in the
  74.  extension word.
  75.  
  76.  The physical key number can be used to assign different actions to sets of
  77.  keys that generate the same keypress code - Return and Enter for example.
  78.  When implementing such a scheme, make sure that the DEFAULT action is that
  79.  assigned to the more-common keypress, eg:
  80.  
  81.    CASE block!24 OF
  82.      WHEN 13:REM Return, Enter or Ctrl-M
  83.        CASE (block!28)>>>16 OF
  84.          WHEN &67: PROCkeypress_ENTER
  85.          WHEN &54: PROCkeypress_CTRL_M
  86.          OTHERWISE:PROCkeypress_RETURN
  87.        ENCASE
  88.  
  89.  This ensures sensible operation with future keyboards, and with keypresses
  90.  not generated by the keyboard - see following section. Please note that to
  91.  allow the Logo and Menu keys to act as modifiers, they do not return a valid
  92.  physical key number when pressed in isolation.
  93.  
  94.  Problems
  95.  ~~~~~~~~
  96.  RemV block mode cannot sensibly be used - word values in the buffer will be
  97.  truncated to their lowest eight bits.
  98.  
  99.  Key codes inserted into the buffer by software, rather than by the keyboard,
  100.  do not normally have modifier or physical keys associated with them (unless
  101.  the new InsV call is used). When delivered to a Wimp program it will report
  102.  the state of the keyboard modifiers at the time of the simulated keypress, and
  103.  the physical key number of the last REAL keypress. This physical key number
  104.  will NOT match the key code inserted. This is why Wimp applications must be
  105.  careful about interpreting the physical key number, as described above.
  106.  
  107.  The DeepKeys module does not pass keyboard buffer events on to existing
  108.  claimants of the InsV, RemV and CnpV vectors, and so must be loaded first to
  109.  avoid disabling some utilities - hence the allocated install position
  110.  "<Boot$ToBeLoaded>.!!DeepKeys". This is a consequence of the way these vectors
  111.  are used, and cannot be avoided without vector claimant prioritisation, as
  112.  performed by Cerilica's VectorExtend module.
  113.  
  114.  
  115.  DeepKeys is copyright Cerilica Limited and was written by Simon Birtwistle.
  116.  <http://www.cerilica.com/>                      <mailto:simon@cerilica.com>
  117.  
  118.