home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / utilities / organisers / fasttask / !FastTask / Docs / WimpKey < prev   
Encoding:
Text File  |  1995-01-04  |  13.4 KB  |  550 lines
  1.  
  2. The WimpKey module (version 1.10)
  3. =================================
  4.  
  5.           Free Distribution Software (FreeWare) by Jason Williams
  6.                          Extended by Sam Kington
  7.                    This software is NOT Public Domain
  8.  
  9. 1. This software remains the copyright of the authors, Jason Williams and
  10.    Sam Kington, but it may be freely distributed and used, provided that when being
  11.    distributed on its own:
  12.    a) it is kept as a whole- The module and this documentation file must be
  13.       distributed, unmodified, together.
  14.    b) no charge is made for any copying or distribution other than third
  15.       party transmission costs (eg disc cost, postage, phone charges).
  16.  
  17. 2. The authors do not accept any responsibility for any use or misuse of
  18.    the software or any consequences thereof, and make no guarantees of
  19.    continued support for the module.
  20.  
  21. 3. This module may be included as part of any product, including commercial
  22.    software, free of charge, so long as its use is acknowledged in the
  23.    accompanying documentation. Be aware of item 2.
  24.    
  25.                                     --===--
  26.  
  27. The WimpKey module provides a very simple service to help with using
  28. dynamic key bindings in WIMP applications.
  29.  
  30. Dynamic key bindings are "hot keys" for common operations, that are set in
  31. some sort of configuration file which the user may edit in order to change the
  32. keys used in the program to more suitable values. It is important that programs
  33. allow such configuration, both to enable people to configure the program to
  34. their own tastes, and also to make internationalisation much simpler.
  35.  
  36. As well as making life easier for the programmer (it takes a long time to
  37. code this sort of thing if you're starting from scratch), it allows this
  38. table to be shared by all applications on the desktop (reducing their size),
  39. and it helps to enforce a standard naming convention for all of these keys.
  40. Hopefully it will also encourage other lazy authors to actually put key
  41. bindings in to their programs now!
  42.  
  43. An additional advantage is that WimpKey provides extra key codes for certain
  44. key combinations: Return (rather than Ctrl-M), Ctrl-Shift-A to Z, as well as
  45. the more esoteric Keypad-* and Alt-Ctrl-Shift-Tab, among others. As anyone
  46. who uses Impression regularly will know, there are a limited number of
  47. hotkeys available: this should give you a bit more breathing space.
  48.  
  49. The module provides 3 SWI commands, as well as a * command:
  50.  
  51.  
  52. The command: *ListWimpKeys
  53. ==========================
  54.  
  55. This command simply produces a list of the available wimp key mappings,
  56. showing the hexadecimal WIMP key code (as returned by Wimp Poll on key events)
  57. and the WimpKey string used to represent that key.
  58.  
  59.  
  60. SWI "WimpKey_CodeToString" &47BC0
  61. =================================
  62.  
  63. Entry:       R0 = WIMP key code
  64. Exit:        R0 = pointer to the equivalent string (0-terminated), or
  65.                   NULL (0) if the keycode is unknown
  66.              All other registers preserved
  67.  
  68. Description:
  69.              This SWI takes a normal WIMP key code, and produces the relevant
  70.              keycode string. This is intended for use where your program
  71.              knows the key code of a key, and wishes to add a textual reminder
  72.              alongside a menu item (for example) for the user.
  73.  
  74.              NOTE that the string returned is zero terminated, and that it is
  75.              in the module's private workspace. It will be overwritten by the
  76.              next call to this SWI, so if you want to use the string, you must
  77.              copy it into your own workspace first.
  78.  
  79.              Keycode strings are a maximum of 9 characters long including the
  80.              terminating NULL character.
  81.  
  82.  
  83. SWI "WimpKey_StringToCode" &47BC1
  84. =================================
  85.  
  86. Entry:       R0 = pointer to keycode string
  87. Exit:        R0 = The related wimp key code, or -1 if the string was not found
  88.              All other registers preserved
  89.  
  90. Description:
  91.              This SWI takes a key code string (which may be up to 9 characters
  92.              long, including the terminator. The terminator can be any ctrl-
  93.              character (i.e. any char in the range ASCII 0 to ASCII 31)), and
  94.              converts it into a WIMP key code number.
  95.  
  96.              This is intended for use when reading a configuration file or
  97.              otherwise editing key codes (e.g. like the Impression style
  98.              editor's hotkey entry thingo) - the user can enter a value as
  99.              a meaningful string, and your program can convert this into a
  100.              WIMP key code for itself using the SWI.
  101.  
  102.              Note that the string passed in must EXACTLY match the keycode
  103.              string (case and all).
  104.  
  105.              Note also the special values "Return" and "Enter", which are
  106.              explained at the end of this text.
  107.  
  108. SWI "WimpKey_CodeToExtCode" &47BC2
  109. =================================
  110.  
  111. Entry:       R0 = key code provided by Wimp_Poll
  112. Exit:        R0 = extended key code if there is one available, otherwise preserved.
  113.              All other registers preserved
  114.  
  115. Description:
  116.              This SWI takes the key code returned by Wimp_Poll, and checks
  117.              whether it matches any of the extended codes provided by
  118.              WimpKey; if so, it converts it, otherwise it leaves it as it is.
  119.              This SWI should be used in preference to manually converting the
  120.              raw value into a WimpKey-friendly code, like you had to do with
  121.              previous versions of WimpKey, as a) it's faster, and b) it's
  122.              done for you.
  123.  
  124. Current keycode definitions
  125. ===========================
  126.  
  127. Here is the output from the *ListWimpKeys command on the current version
  128. of the module. Codes prefixed with a '*' are new to this version. Codes over
  129. &1000 can only be produced with the SWI WimpKey_CodeToExtCode (see notes
  130. below). As is standard on Acorn machines, ⇧ stands for Shift and ^ for Ctrl;
  131. the Alt key is nowhere near as commonly used so there isn't really a standard
  132. symbol for it, but ~ seems as standard as anything.
  133.  
  134. *ListWimpKeys
  135.  
  136. Available WIMP key codes: (hit SHIFT to scroll)
  137.  Keycode String
  138.   &0000  ^@
  139.   &0001  ^A
  140.   &0002  ^B
  141.   &0003  ^C
  142.   &0004  ^D
  143.   &0005  ^E
  144.   &0006  ^F
  145.   &0007  ^G
  146.   &0008  ^H
  147.   &0009  ^I
  148.   &000A  ^J
  149.   &000B  ^K
  150.   &000C  ^L
  151.   &000D  ^M
  152.   &000E  ^N
  153.   &000F  ^O
  154.   &0010  ^P
  155.   &0011  ^Q
  156.   &0012  ^R
  157.   &0013  ^S
  158.   &0014  ^T
  159.   &0015  ^U
  160.   &0016  ^V
  161.   &0017  ^W
  162.   &0018  ^X
  163.   &0019  ^Y
  164.   &001A  ^Z
  165.   &001B  Escape
  166.   &001B  ESC
  167. * &001C  ^\
  168. * &001D  ^]
  169.   &001E  Home
  170. * &001F  ^-
  171.   &0020  Space
  172.   &0020  SPC
  173.   &0021  !
  174.   &0022  "
  175.   &0023  #
  176.   &0024  $
  177.   &0025  %
  178.   &0026  &
  179.   &0027  '
  180.   &0028  (
  181.   &0029  )
  182.   &002A  *
  183.   &002B  +
  184.   &002C  ,
  185.   &002D  -
  186.   &002E  .
  187.   &002F  /
  188.   &0030  0
  189.   &0031  1
  190.   &0032  2
  191.   &0033  3
  192.   &0034  4
  193.   &0035  5
  194.   &0036  6
  195.   &0037  7
  196.   &0038  8
  197.   &0039  9
  198.   &003A  :
  199.   &003B  ;
  200.   &003C  <
  201.   &003D  =
  202.   &003E  >
  203.   &003F  ?
  204.   &0040  @
  205.   &0041  A
  206.   &0042  B
  207.   &0043  C
  208.   &0044  D
  209.   &0045  E
  210.   &0046  F
  211.   &0047  G
  212.   &0048  H
  213.   &0049  I
  214.   &004A  J
  215.   &004B  K
  216.   &004C  L
  217.   &004D  M
  218.   &004E  N
  219.   &004F  O
  220.   &0050  P
  221.   &0051  Q
  222.   &0052  R
  223.   &0053  S
  224.   &0054  T
  225.   &0055  U
  226.   &0056  V
  227.   &0057  W
  228.   &0058  X
  229.   &0059  Y
  230.   &005A  Z
  231.   &005B  [
  232.   &005C  \
  233.   &005D  ]
  234.   &005E  ^
  235.   &005F  _
  236.   &0060  `
  237.   &0061  a
  238.   &0062  b
  239.   &0063  c
  240.   &0064  d
  241.   &0065  e
  242.   &0066  f
  243.   &0067  g
  244.   &0068  h
  245.   &0069  i
  246.   &006A  j
  247.   &006B  k
  248.   &006C  l
  249.   &006D  m
  250.   &006E  n
  251.   &006F  o
  252.   &0070  p
  253.   &0071  q
  254.   &0072  r
  255.   &0073  s
  256.   &0074  t
  257.   &0075  u
  258.   &0076  v
  259.   &0077  w
  260.   &0078  x
  261.   &0079  y
  262.   &007A  z
  263.   &007B  {
  264.   &007C  |
  265.   &007D  }
  266.   &007E  ~
  267.   &007F  Delete
  268.   &007F  DEL
  269.   &0180  Print
  270.   &0181  F1
  271.   &0182  F2
  272.   &0183  F3
  273.   &0184  F4
  274.   &0185  F5
  275.   &0186  F6
  276.   &0187  F7
  277.   &0188  F8
  278.   &0189  F9
  279.   &018A  Tab
  280.   &018B  Copy
  281.   &018C  Left
  282.   &018D  Right
  283.   &018E  Down
  284.   &018F  Up
  285.   &018C  ⇦
  286.   &018D  ⇨
  287.   &018E  ⇩
  288.   &018F  ⇧
  289.   &0190  ⇧Print
  290.   &0191  ⇧F1
  291.   &0192  ⇧F2
  292.   &0193  ⇧F3
  293.   &0194  ⇧F4
  294.   &0195  ⇧F5
  295.   &0196  ⇧F6
  296.   &0197  ⇧F7
  297.   &0198  ⇧F8
  298.   &0199  ⇧F9
  299.   &019A  ⇧Tab
  300.   &019B  ⇧Copy
  301.   &019C  ⇧Left
  302.   &019C  ⇧⇦
  303.   &019D  ⇧Right
  304.   &019D  ⇧⇨
  305.   &019E  PageDn
  306.   &019E  ⇧Down
  307.   &019F  PageUp
  308.   &019F  ⇧Up
  309.   &01A0  ^Print
  310.   &01A1  ^F1
  311.   &01A2  ^F2
  312.   &01A3  ^F3
  313.   &01A4  ^F4
  314.   &01A5  ^F5
  315.   &01A6  ^F6
  316.   &01A7  ^F7
  317.   &01A8  ^F8
  318.   &01A9  ^F9
  319.   &01AA  ^Tab
  320.   &01AB  ^Copy
  321.   &01AC  ^Left
  322.   &01AD  ^Right
  323.   &01AE  ^Down
  324.   &01AF  ^Up
  325.   &01AC  ^⇦
  326.   &01AD  ^⇨
  327.   &01AE  ^⇩
  328.   &01AF  ^⇧
  329.   &01B0  ^⇧Print
  330.   &01B1  ^⇧F1
  331.   &01B2  ^⇧F2
  332.   &01B3  ^⇧F3
  333.   &01B4  ^⇧F4
  334.   &01B5  ^⇧F5
  335.   &01B6  ^⇧F6
  336.   &01B7  ^⇧F7
  337.   &01B8  ^⇧F8
  338.   &01B9  ^⇧F9
  339.   &01BA  ^⇧Tab
  340.   &01BB  ^⇧Copy
  341.   &01BC  ^⇧Left
  342.   &01BD  ^⇧Right
  343.   &01BE  ^⇧Down
  344.   &01BF  ^⇧Up
  345.   &01BC  ^⇧⇦
  346.   &01BD  ^⇧⇨
  347.   &01BE  ^⇧⇩
  348.   &01BF  ^⇧⇧
  349.   &01BE  ^PageDn
  350.   &01BE  ^⇧Down
  351.   &01BF  ^PageUp
  352.   &01BF  ^⇧Up
  353.   &01CA  F10
  354.   &01CB  F11
  355.   &01CC  F12
  356.   &01CD  Insert
  357.   &01DA  ⇧F10
  358.   &01DB  ⇧F11
  359.   &01DC  ⇧F12
  360.   &01DD  ⇧Insert
  361.   &01EA  ^F10
  362.   &01EB  ^F11
  363.   &01EC  ^F12
  364.   &01ED  ^Insert
  365.   &01FA  ^⇧F10
  366.   &01FB  ^⇧F11
  367.   &01FC  ^⇧F12
  368.   &01FD  ^⇧Insert
  369.   &1000  Return
  370.   &1000  Enter
  371. * &1003  Pad#
  372. * &1008  Back
  373. * &1010  ⇧Return
  374. * &1018  ⇧Back
  375. * &101B  ⇧Escape
  376. * &101E  ⇧Home
  377. * &101F  ⇧Delete
  378. * &1023  ^Pad#
  379. * &102B  ^Escape
  380. * &102E  ^Home
  381. * &102F  ^Delete
  382. * &1033  ^⇧Pad#
  383. * &103B  ^⇧Esc
  384. * &103E  ^⇧Home
  385. * &103F  ^⇧Del
  386. * &104A  Pad*
  387. * &104B  Pad+
  388. * &1050  ⇧Pad0
  389. * &1051  ⇧Pad1
  390. * &1052  ⇧Pad2
  391. * &1053  ⇧Pad3
  392. * &1054  ⇧Pad4
  393. * &1055  ⇧Pad5
  394. * &1056  ⇧Pad6
  395. * &1057  ⇧Pad7
  396. * &1058  ⇧Pad8
  397. * &1059  ⇧Pad9
  398. * &105D  ⇧Pad-
  399. * &105E  ⇧Pad.
  400. * &105F  ⇧Pad/
  401. * &1060  ^Pad0
  402. * &1061  ^Pad1
  403. * &1062  ^Pad2
  404. * &1063  ^Pad3
  405. * &1064  ^Pad4
  406. * &1065  ^Pad5
  407. * &1066  ^Pad6
  408. * &1067  ^Pad7
  409. * &1068  ^Pad8
  410. * &1069  ^Pad9
  411. * &106A  ^Pad*
  412. * &106B  ^Pad+
  413. * &106D  ^Pad-
  414. * &106E  ^Pad.
  415. * &106F  ^Pad/
  416. * &1070  ^⇧Pad0
  417. * &1071  ^⇧Pad1
  418. * &1072  ^⇧Pad2
  419. * &1073  ^⇧Pad3
  420. * &1074  ^⇧Pad4
  421. * &1075  ^⇧Pad5
  422. * &1076  ^⇧Pad6
  423. * &1077  ^⇧Pad7
  424. * &1078  ^⇧Pad8
  425. * &1079  ^⇧Pad9
  426. * &107A  ^⇧Pad*
  427. * &107B  ^⇧Pad+
  428. * &107D  ^⇧Pad-
  429. * &107E  ^⇧Pad.
  430. * &107F  ^⇧Pad/
  431. * &1080  ~Tab
  432. * &1090  ~⇧Tab
  433. * &10A0  ~^Tab
  434. * &10B0  ~^⇧Tab
  435.   &2000  ^⇧@
  436.   &2001  ^⇧A
  437.   &2002  ^⇧B
  438.   &2003  ^⇧C
  439.   &2004  ^⇧D
  440.   &2005  ^⇧E
  441.   &2006  ^⇧F
  442.   &2007  ^⇧G
  443.   &2008  ^⇧H
  444.   &2009  ^⇧I
  445.   &200A  ^⇧J
  446.   &200B  ^⇧K
  447.   &200C  ^⇧L
  448.   &200D  ^⇧M
  449.   &200E  ^⇧N
  450.   &200F  ^⇧O
  451.   &2010  ^⇧P
  452.   &2011  ^⇧Q
  453.   &2012  ^⇧R
  454.   &2013  ^⇧S
  455.   &2014  ^⇧T
  456.   &2015  ^⇧U
  457.   &2016  ^⇧V
  458.   &2017  ^⇧W
  459.   &2018  ^⇧X
  460.   &2019  ^⇧Y
  461.   &201A  ^⇧Z
  462. * &201C  ^⇧\
  463. * &201D  ^⇧]
  464. * &201F  ^⇧-
  465.  
  466.  
  467. (If you spot any errors in this list, please let me know ASAP!)
  468.  
  469.  
  470. SPECIAL NOTES
  471. =============
  472.  
  473. Please note that there are some keys which do not normally have unique key
  474. numbers: for example, ^M, Return, and Enter all share code &0D, the up and
  475. down cursor arrows share many codes in common with the page up and down keys,
  476. numeric keypad keys are indistinguishable from the other numeric keys and
  477. some keys produce the same value irrespective of whether Shift or Ctrl are
  478. held down.
  479.  
  480. The only way of telling these keys apart is to check if certain shifting keys
  481. (Shift, Ctrl, Alt) are held down when you recieve a key event - a not
  482. entirely cast-iron practice, as key presses can be buffered for some time
  483. before you receive an event. Usually it works fine: keypresses usually get to
  484. their receiver almost instantaneously, and you've got to be pretty quick to
  485. let go of the keys early enough to foul things up. (Especially as most
  486. people, if anything, let go of the shifting key *after* they let go of the
  487. other key, not before).
  488.  
  489. In previous versions of the module you had to convert the raw values
  490. manually; with this version there is a SWI, WimpKey_CodeToExtCode, that will
  491. do it for you. That's just as well, as all the key combinations that can be
  492. told apart under standard RISC OS are now catered for; mainly numeric keypad
  493. keypresses, but also things like Ctrl-Home, Shift-Escape and other such
  494. stuff.
  495.  
  496. From version 1.01 of the module onwards there are some duplicate bindings.
  497. All of the old mappings are still available for string lookup, but looking up
  498. a number in the list will return the new string variants:
  499.  
  500.   SPC now also has a mapping Space
  501.   DEL                        Delete
  502.   ESC                        Escape
  503.  
  504. and there are new cursor-key mappings (Left, Right, Up, Down, etc)
  505.  
  506.  
  507. Contacting the authors
  508. ======================
  509.  
  510. Bug reports, suggestions, or other miscellaneous comments are always welcome,
  511. but as there are now two authors of this module you may be confused who to
  512. contact. Don't let that put you off: any general comments will usually be
  513. forwarded between the two of us. But in general, anything relating to the
  514. general core of the module should be sent to Jason Williams, the original
  515. author of the module, and anything about the new keycodes should be sent to
  516. Sam Kington.
  517.  
  518. Here's how to get to us.
  519.  
  520. Jason Williams
  521. ==============
  522.  
  523. Email: jason@cconcepts.co.uk
  524. or snail mail at Computer Concepts.
  525.                 
  526. *Disclaimer*:Although I work for Computer Concepts, and this is the only
  527. permanent contact address I can currently supply, development of/support for
  528. WimpKey has absolutely nothing whatsoever to do with Computer Concepts
  529.  
  530. Any enquiries to Computer Concepts about this module will most likely be
  531. met with a blank, uncomprehending stare, so make sure you ask *me*.
  532.  
  533. If you wish to use this module in a commercial application, it would be a good
  534. idea to contact Jason to see if there is a newer version of the module
  535. available.
  536.  
  537. Sam Kington
  538. ===========
  539.  
  540. Email: 926286ki@udcf.gla.ac.uk (until June 1996)
  541.  
  542. Snail mail: Flat 2/1           (until June 1995)
  543.             44 Hotspur St
  544.             Glasgow G20 8NL
  545.             
  546.          or Merlhiot           (permanent back-up)
  547.             24420 Savignac les Eglises
  548.             FRANCE
  549.  
  550.