home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / atlanta / Docs / WKeyDocs < prev   
Encoding:
Text File  |  1994-01-27  |  10.2 KB  |  431 lines
  1.  
  2. The WimpKey module (version 1.01)
  3. =================================
  4.  
  5.           Free Distribution Software (FreeWare) by Jason Williams
  6.                    This software is NOT Public Domain
  7.  
  8. 1. This software remains the copyright of the author, Jason Williams, but it
  9.    may be freely distributed and used, provided that when being distributed
  10.    on its own:
  11.    a) it is kept as a whole- The module and this documentation file must be
  12.       distributed, unmodified, together.
  13.    b) no charge is made for any copying or distribution other than third
  14.       party transmission costs (eg disc cost, postage, phone charges).
  15.  
  16. 2. The author does not accept any responsibility for any use or misuse of
  17.    the software or any consequences thereof, and makes no guarantees of
  18.    continued support for the module.
  19.  
  20. 3. This module may be included as part of any product, including commercial
  21.    software, free of charge, so long as its use is acknowledged in the
  22.    accompanying documentation. Be aware of item 2.
  23.  
  24.                                     --===--
  25.  
  26. The WimpKey module provides a very simple service to help with using
  27. dynamic key bindings in WIMP applications.
  28.  
  29. Dynamic key bindings are "hot keys" for common operations, that are set in
  30. some sort of configuration file which the user may edit in order to change the
  31. keys used in the program to more suitable values. It is important that programs
  32. allow such configuration, both to enable people to configure the program to
  33. their own tastes, and also to make internationalisation much simpler.
  34.  
  35. As well as making life easier for the programmer (it took me half an hour
  36. to enter all of the keycodes), it allows this table to be shared by all
  37. applications on the desktop (reducing their size), and it helps to enforce
  38. a standard naming convention for all of these keys. I hope it will also
  39. encourage lazy authors like myself to actually put key bindings in to their
  40. programs now!
  41.  
  42. The module provides 2 SWI commands, as well as a * command:
  43.  
  44.  
  45. The command: *ListWimpKeys
  46. ==========================
  47.  
  48. This command simply produces a list of the available wimp key mappings,
  49. showing the hexadecimal WIMP key code (as returned by Wimp Poll on key events)
  50. and the WimpKey string used to represent that key.
  51.  
  52.  
  53. SWI "WimpKey_CodeToString" &47BC0
  54. =================================
  55.  
  56. Entry:       R0 = WIMP key code
  57. Exit:        R0 = pointer to the equivalent string (0-terminated), or
  58.                   NULL (0) if the keycode is unknown
  59.              All other registers preserved
  60.  
  61. Description:
  62.              This SWI takes a normal WIMP key code, and produces the relevant
  63.              keycode string. This is intended for use where your program
  64.              knows the key code of a key, and wishes to add a textual reminder
  65.              alongside a menu item (for example) for the user.
  66.  
  67.              NOTE that the string returned is zero terminated, and that it is
  68.              in the module's private workspace. It will be overwritten by the
  69.              next call to this SWI, so if you want to use the string, you must
  70.              copy it into your own workspace first.
  71.  
  72.              Keycode strings are a maximum of 9 characters long including the
  73.              terminating NULL character.
  74.  
  75.  
  76. SWI "WimpKey_StringToCode" &47BC1
  77. =================================
  78.  
  79. Entry:       R0 = pointer to keycode string
  80. Exit:        R0 = The related wimp key code, or -1 if the string was not found
  81.              All other registers preserved
  82.  
  83. Description:
  84.              This SWI takes a key code string (which may be up to 9 characters
  85.              long, including the terminator. The terminator can be any ctrl-
  86.              character (i.e. any char in the range ASCII 0 to ASCII 31)), and
  87.              converts it into a WIMP key code number.
  88.  
  89.              This is intended for use when reading a configuration file or
  90.              otherwise editing key codes (e.g. like the Impression style
  91.              editor's hotkey entry thingo) - the user can enter a value as
  92.              a meaningful string, and your program can convert this into a
  93.              WIMP key code for itself using the SWI.
  94.  
  95.              Note that the string passed in must EXACTLY match the keycode
  96.              string (case and all).
  97.  
  98.              Note also the special values "Return" and "Enter", which are
  99.              explained at the end of this text.
  100.  
  101.  
  102. Current keycode definitions
  103. ===========================
  104.  
  105. Here is the output from the *ListWimpKeys command on the current version
  106. of the module:
  107.  
  108. *listwimpkeys
  109. Available WIMP key codes: (hit SHIFT to scroll)
  110.  Keycode String
  111.   &0000  ^@
  112.   &0001  ^A
  113.   &0002  ^B
  114.   &0003  ^C
  115.   &0004  ^D
  116.   &0005  ^E
  117.   &0006  ^F
  118.   &0007  ^G
  119.   &0008  ^H
  120.   &0009  ^I
  121.   &000A  ^J
  122.   &000B  ^K
  123.   &000C  ^L
  124.   &000D  ^M
  125.   &000E  ^N
  126.   &000F  ^O
  127.   &0010  ^P
  128.   &0011  ^Q
  129.   &0012  ^R
  130.   &0013  ^S
  131.   &0014  ^T
  132.   &0015  ^U
  133.   &0016  ^V
  134.   &0017  ^W
  135.   &0018  ^X
  136.   &0019  ^Y
  137.   &001A  ^Z
  138.   &001B  Escape
  139.   &001B  ESC
  140.   &001E  Home
  141.   &0020  Space
  142.   &0020  SPC
  143.   &0021  !
  144.   &0022  "
  145.   &0023  #
  146.   &0024  $
  147.   &0025  %
  148.   &0026  &
  149.   &0027  '
  150.   &0028  (
  151.   &0029  )
  152.   &002A  *
  153.   &002B  +
  154.   &002C  ,
  155.   &002D  -
  156.   &002E  .
  157.   &002F  /
  158.   &0030  0
  159.   &0031  1
  160.   &0032  2
  161.   &0033  3
  162.   &0034  4
  163.   &0035  5
  164.   &0036  6
  165.   &0037  7
  166.   &0038  8
  167.   &0039  9
  168.   &003A  :
  169.   &003B  ;
  170.   &003C  <
  171.   &003D  =
  172.   &003E  >
  173.   &003F  ?
  174.   &0040  @
  175.   &0041  A
  176.   &0042  B
  177.   &0043  C
  178.   &0044  D
  179.   &0045  E
  180.   &0046  F
  181.   &0047  G
  182.   &0048  H
  183.   &0049  I
  184.   &004A  J
  185.   &004B  K
  186.   &004C  L
  187.   &004D  M
  188.   &004E  N
  189.   &004F  O
  190.   &0050  P
  191.   &0051  Q
  192.   &0052  R
  193.   &0053  S
  194.   &0054  T
  195.   &0055  U
  196.   &0056  V
  197.   &0057  W
  198.   &0058  X
  199.   &0059  Y
  200.   &005A  Z
  201.   &005B  [
  202.   &005C  \
  203.   &005D  ]
  204.   &005E  ^
  205.   &005F  _
  206.   &0060  `
  207.   &0061  a
  208.   &0062  b
  209.   &0063  c
  210.   &0064  d
  211.   &0065  e
  212.   &0066  f
  213.   &0067  g
  214.   &0068  h
  215.   &0069  i
  216.   &006A  j
  217.   &006B  k
  218.   &006C  l
  219.   &006D  m
  220.   &006E  n
  221.   &006F  o
  222.   &0070  p
  223.   &0071  q
  224.   &0072  r
  225.   &0073  s
  226.   &0074  t
  227.   &0075  u
  228.   &0076  v
  229.   &0077  w
  230.   &0078  x
  231.   &0079  y
  232.   &007A  z
  233.   &007B  {
  234.   &007C  |
  235.   &007D  }
  236.   &007E  ~
  237.   &007F  Delete
  238.   &007F  DEL
  239.   &0180  Print
  240.   &0181  F1
  241.   &0182  F2
  242.   &0183  F3
  243.   &0184  F4
  244.   &0185  F5
  245.   &0186  F6
  246.   &0187  F7
  247.   &0188  F8
  248.   &0189  F9
  249.   &018A  Tab
  250.   &018B  Copy
  251.   &018C  Left
  252.   &018D  Right
  253.   &018E  Down
  254.   &018F  Up
  255.   &018C  
  256.   &018D     
  257.   &018E  
  258.   &018F  
  259.   &0190   Print
  260.   &0191   F1
  261.   &0192   F2
  262.   &0193   F3
  263.   &0194   F4
  264.   &0195   F5
  265.   &0196   F6
  266.   &0197   F7
  267.   &0198   F8
  268.   &0199   F9
  269.   &019A   Tab
  270.   &019B   Copy
  271.   &019C   Left
  272.   &019C  
  273.   &019D   Right
  274.   &019D     
  275.   &019E  PageDn
  276.   &019E   Down
  277.   &019F  PageUp
  278.   &019F   Up
  279.   &01A0  ^Print
  280.   &01A1  ^F1
  281.   &01A2  ^F2
  282.   &01A3  ^F3
  283.   &01A4  ^F4
  284.   &01A5  ^F5
  285.   &01A6  ^F6
  286.   &01A7  ^F7
  287.   &01A8  ^F8
  288.   &01A9  ^F9
  289.   &01AA  ^Tab
  290.   &01AB  ^Copy
  291.   &01AC  ^Left
  292.   &01AD  ^Right
  293.   &01AE  ^Down
  294.   &01AF  ^Up
  295.   &01AC  ^
  296.   &01AD  ^  
  297.   &01AE  ^
  298.   &01AF  ^
  299.   &01B0  ^ Print
  300.   &01B1  ^ F1
  301.   &01B2  ^ F2
  302.   &01B3  ^ F3
  303.   &01B4  ^ F4
  304.   &01B5  ^ F5
  305.   &01B6  ^ F6
  306.   &01B7  ^ F7
  307.   &01B8  ^ F8
  308.   &01B9  ^ F9
  309.   &01BA  ^ Tab
  310.   &01BB  ^ Copy
  311.   &01BC  ^ Left
  312.   &01BD  ^ Right
  313.   &01BC  ^
  314.   &01BD  ^  
  315.   &01BE  ^PageDn
  316.   &01BE  ^ Down
  317.   &01BF  ^PageUp
  318.   &01BF  ^ Up
  319.   &01CA  F10
  320.   &01CB  F11
  321.   &01CC  F12
  322.   &01CD  Insert
  323.   &01DA   F10
  324.   &01DB   F11
  325.   &01DC   F12
  326.   &01DD   Insert
  327.   &01EA  ^F10
  328.   &01EB  ^F11
  329.   &01EC  ^F12
  330.   &01ED  ^Insert
  331.   &01FA  ^ F10
  332.   &01FB  ^ F11
  333.   &01FC  ^ F12
  334.   &01FD  ^ Insert
  335.  
  336.   &1000  Return
  337.   &1000  Enter
  338.  
  339.   &2000  ^ @
  340.   &2001  ^ A
  341.   &2002  ^ B
  342.   &2003  ^ C
  343.   &2004  ^ D
  344.   &2005  ^ E
  345.   &2006  ^ F
  346.   &2007  ^ G
  347.   &2008  ^ H
  348.   &2009  ^ I
  349.   &200A  ^ J
  350.   &200B  ^ K
  351.   &200C  ^ L
  352.   &200D  ^ M
  353.   &200E  ^ N
  354.   &200F  ^ O
  355.   &2010  ^ P
  356.   &2011  ^ Q
  357.   &2012  ^ R
  358.   &2013  ^ S
  359.   &2014  ^ T
  360.   &2015  ^ U
  361.   &2016  ^ V
  362.   &2017  ^ W
  363.   &2018  ^ X
  364.   &2019  ^ Y
  365.   &201A  ^ Z
  366.  
  367. (If you spot any errors in this list, please let me know ASAP!)
  368.  
  369.  
  370. SPECIAL NOTES
  371. =============
  372.  
  373. Please note that there are some keys which do not have unique key numbers
  374. (for example ^M, Return, and Enter all share code &0D, the up and down
  375. cursor arrows share many codes in common with the page up and down keys, and
  376. numeric keypad keys are indistinguishable from the other numeric keys)
  377.  
  378. The only way of telling these keys apart is to check if certain keys are held
  379. down when you recieve a key event - a dangerous practice, as key presses
  380. can be buffered for some time before you recieve an event. About the only
  381. case that I feel really matters is distinguishing ^M from return, which you
  382. should special-case in your program.
  383.  
  384. To reflect this, I have added the special keycode &1000 which maps to the
  385. key "Return". This allows the user to specify the Return key specifically
  386. instead of ^M. However, note that it is entirely up to your program to
  387. realise that "Return" means a code of &0D with ctrl undepressed, while "^M"
  388. means a keypress of M with ctrl depressed. Comparing a normal WIMP key code
  389. to the &1000 value for return will fail to work!
  390.  
  391. There is also a new set of bindings for ctrl-shift-letter keypresses: For
  392. these, the WIMP returns values between 1 and 26 (inclusive), the same as
  393. for ctrl-letter keys: In this case, the client application must check if
  394. the SHIFT key is depressed when the keypress is recieved- if this is the case,
  395. and the keycode given by the WIMP was <= 26 then add &2000 to the key code
  396. and look this number up in your bindings.
  397.  
  398. In version 1.01 of the module, I have added some duplicate bindings. All of
  399. the old mappings are still available for string lookup, but looking up a number
  400. in the list will return the new string variants:
  401.  
  402.   SPC now also has a mapping Space
  403.   DEL                        Delete
  404.   ESC                        Escape
  405.  
  406. and there are new cursor-key mappings (Left, Right, Up, Down, etc)
  407.  
  408.  
  409. Contacting the author
  410. =====================
  411.  
  412. Any bug reports, suggestions, etc. can be sent to me at:
  413.   jason@cconcepts.co.uk
  414.  
  415. or snail mail me at Computer Concepts.
  416.  
  417. If you wish to use this module in a commercial application, it would be a good
  418. idea to contact me to see if there is a newer version of the module available.
  419.  
  420.  
  421. Disclaimer
  422. ==========
  423.  
  424. Although I now work for Computer Concepts, and this is the only permanent
  425. contact address I can currently supply, development of/support for WimpKey
  426. has absolutely nothing whatsoever to do with Computer Concepts
  427.  
  428. Any enquiries to Computer Concepts about this module will most likely be
  429. met with a blank, uncomprehending stare, so make sure you ask *me*.
  430.  
  431.