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