home *** CD-ROM | disk | FTP | other *** search
- The WimpKey module
- ==================
-
- Free Distribution Software (FreeWare) by Jason Williams
- This software is NOT Public Domain
-
- 1. This software remains the copyright of the author, Jason Williams, but it
- may be freely distributed and used, provided that when being distributed
- on its own:
- a) it is kept as a whole- The module and this documentation file must be
- distributed, unmodified, together.
- b) no charge is made for any copying or distribution other than third
- party transmission costs (eg disc cost, postage, phone charges).
-
- 2. The author does not accept any responsibility for any use or misuse of
- the software or any consequences thereof, and makes no guarantees of
- continued support for the module.
-
- 3. This module may be included as part of any product, including commercial
- software, free of charge, so long as its use is acknowledged in the
- accompanying documentation. Be aware of item 2.
-
- Slight modifications (style mainly) by Sam Kington (5th January 1994) - see
- end of documentation, and notes between “***”.
-
- --===--
-
- The WimpKey module provides a very simple service to help with using
- dynamic key bindings in WIMP applications.
-
- Dynamic key bindings are "hot keys" for common operations, that are set in
- some sort of configuration file which the user may edit in order to change the
- keys used in the program to more suitable values. It is important that programs
- allow such configuration, both to enable people to configure the program to
- their own tastes, and also to make internationalisation much simpler.
-
- As well as making life easier for the programmer (it took me half an hour
- to enter all of the keycodes), it allows this table to be shared by all
- applications on the desktop (reducing their size), and it helps to enforce
- a standard naming convention for all of these keys. I hope it will also
- encourage lazy authors like myself to actually put key bindings in to their
- programs now!
-
- The module provides 2 SWI commands, as well as a * command:
-
-
- The command: *ListWimpKeys
- ==========================
-
- This command simply produces a list of the available wimp key mappings,
- showing the hexadecimal WIMP key code (as returned by Wimp Poll on key events)
- and the WimpKey string used to represent that key.
-
-
- SWI "WimpKey_CodeToString" &47BC0
- =================================
-
- Entry: R0 = WIMP key code
- Exit: R0 = pointer to the equivalent string (0-terminated), or
- NULL (0) if the keycode is unknown
- All other registers preserved
-
- Description:
- This SWI takes a normal WIMP key code, and produces the relevant
- keycode string. This is intended for use where your program
- knows the key code of a key, and wishes to add a textual reminder
- alongside a menu item (for example) for the user.
-
- NOTE that the string returned is zero terminated, and that it is
- in the module's private workspace. It will be overwritten by the
- next call to this SWI, so if you want to use the string, you must
- copy it into your own workspace first.
-
- Keycode strings are a maximum of 9 characters long including the
- terminating NULL character.
-
-
- SWI "WimpKey_StringToCode" &47BC1
- =================================
-
- Entry: R0 = pointer to keycode string
- Exit: R0 = The related wimp key code, or -1 if the string was not found
- All other registers preserved
-
- Description:
- This SWI takes a key code string (which may be up to 9 characters
- long, including the terminator. The terminator can be any ctrl-
- character (i.e. any char in the range ASCII 0 to ASCII 31)), and
- converts it into a WIMP key code number.
-
- This is intended for use when reading a configuration file or
- otherwise editing key codes (e.g. like the Impression style
- editor's hotkey entry thingo) - the user can enter a value as
- a meaningful string, and your program can convert this into a
- WIMP key code for itself using the SWI.
-
- Note that the string passed in must EXACTLY match the keycode
- string (case and all).
-
- Note also the special values "Return" and "Enter", which are
- explained at the end of this text.
-
-
- Current keycode definitions
- ===========================
-
- Here is the output from the *ListWimpKeys command on the current version
- of the module:
- *** Note: modified version (see below for explanation). Original list is in
- file PrevList in the VarEdit directory. ***
-
- *listwimpkeys
- Available WIMP key codes: (hit SHIFT to scroll)
- Keycode String
- &0000 ^@
- &0001 ^A
- &0002 ^B
- &0003 ^C
- &0004 ^D
- &0005 ^E
- &0006 ^F
- &0007 ^G
- &0008 ^H
- &0009 ^I
- &000A ^J
- &000B ^K
- &000C ^L
- &000D ^M
- &000E ^N
- &000F ^O
- &0010 ^P
- &0011 ^Q
- &0012 ^R
- &0013 ^S
- &0014 ^T
- &0015 ^U
- &0016 ^V
- &0017 ^W
- &0018 ^X
- &0019 ^Y
- &001A ^Z
- &001B Esc *** Was “ESC” ***
- &001E Home
- &0020 Space *** Was “SPC” - not very Acorn-style ;-) ***
- &0021 !
- &0022 "
- &0023 #
- &0024 $
- &0025 %
- &0026 &
- &0027 '
- &0028 (
- &0029 )
- &002A *
- &002B +
- &002C ,
- &002D -
- &002E .
- &002F /
- &0030 0
- &0031 1
- &0032 2
- &0033 3
- &0034 4
- &0035 5
- &0036 6
- &0037 7
- &0038 8
- &0039 9
- &003A :
- &003B ;
- &003C <
- &003D =
- &003E >
- &003F ?
- &0040 @
- &0041 A
- &0042 B
- &0043 C
- &0044 D
- &0045 E
- &0046 F
- &0047 G
- &0048 H
- &0049 I
- &004A J
- &004B K
- &004C L
- &004D M
- &004E N
- &004F O
- &0050 P
- &0051 Q
- &0052 R
- &0053 S
- &0054 T
- &0055 U
- &0056 V
- &0057 W
- &0058 X
- &0059 Y
- &005A Z
- &005B [
- &005C \
- &005D ]
- &005E ^
- &005F _
- &0060 `
- &0061 a
- &0062 b
- &0063 c
- &0064 d
- &0065 e
- &0066 f
- &0067 g
- &0068 h
- &0069 i
- &006A j
- &006B k
- &006C l
- &006D m
- &006E n
- &006F o
- &0070 p
- &0071 q
- &0072 r
- &0073 s
- &0074 t
- &0075 u
- &0076 v
- &0077 w
- &0078 x
- &0079 y
- &007A z
- &007B {
- &007C |
- &007D }
- &007E ~
- &007F Delete *** Was “DEL” - too much like a printer code ***
- &0180 Print
- &0181 F1
- &0182 F2
- &0183 F3
- &0184 F4
- &0185 F5
- &0186 F6
- &0187 F7
- &0188 F8
- &0189 F9
- &018A Tab
- &018B Copy
- &018C Left *** All arrow keys were ⇦⇨⇩⇧ - contrary to ***
- &018D Right *** Acorn guidelines, as a) ⇧ is already Shift ***
- &018E Down *** and b) in an outline font it looks silly ***
- &018F Up
- &0190 ⇧Print
- &0191 ⇧F1
- &0192 ⇧F2
- &0193 ⇧F3
- &0194 ⇧F4
- &0195 ⇧F5
- &0196 ⇧F6
- &0197 ⇧F7
- &0198 ⇧F8
- &0199 ⇧F9
- &019A ⇧Tab
- &019B ⇧Copy
- &019C ⇧Left
- &019D ⇧Right
- &019E ⇧Down *** Was PgDown and PgUp; should be ***
- &019F ⇧Up *** PageDown and PageUp, but there wasn’t space ***
- &01A0 ^Print
- &01A1 ^F1
- &01A2 ^F2
- &01A3 ^F3
- &01A4 ^F4
- &01A5 ^F5
- &01A6 ^F6
- &01A7 ^F7
- &01A8 ^F8
- &01A9 ^F9
- &01AA ^Tab
- &01AB ^Copy
- &01AC ^Left
- &01AD ^Right
- &01AE ^Down
- &01AF ^Up
- &01B0 ^⇧Print
- &01B1 ^⇧F1
- &01B2 ^⇧F2
- &01B3 ^⇧F3
- &01B4 ^⇧F4
- &01B5 ^⇧F5
- &01B6 ^⇧F6
- &01B7 ^⇧F7
- &01B8 ^⇧F8
- &01B9 ^⇧F9
- &01BA ^⇧Tab
- &01BB ^⇧Copy
- &01BC ^⇧Left
- &01BD ^⇧Right
- &01BE ^⇧Down *** Was ^PgDown and ^PgUp - a rather ***
- &01BF ^⇧Up *** odd way of doing things... ***
- &01CA F10
- &01CB F11
- &01CC F12
- &01CD Insert
- &01DA ⇧F10
- &01DB ⇧F11
- &01DC ⇧F12
- &01DD ⇧Insert
- &01EA ^F10
- &01EB ^F11
- &01EC ^F12
- &01ED ^Insert
- &01FA ^⇧F10
- &01FB ^⇧F11
- &01FC ^⇧F12
- &01FD ^⇧Insert
- &1000 Return
- &1000 Enter
-
- (If you spot any errors in this list, please let me know ASAP!)
-
-
- SPECIAL NOTES
- =============
-
- Please note that there are some keys which do not have unique key numbers
- (for example ^M, Return, and Enter all share code &0D, the up and down
- cursor arrows share many codes in common with the page up and down keys, and
- numeric keypad keys are indistinguishable from the other numeric keys)
-
- The only way of telling these keys apart is to check if certain keys are held
- down when you recieve a key event - a dangerous practice, as key presses
- can be buffered for some time before you recieve an event. About the only
- case that I feel really matters is distinguishing ^M from return, which you
- should special-case in your program.
-
- To reflect this, I have added the special keycode &1000 which maps to the
- key "Return". This allows the user to specify the Return key specifically
- instead of ^M. However, note that it is entirely up to your program to
- realise that "Return" means a code of &0D with ctrl undepressed, while "^M"
- means a keypress of M with ctrl depressed. Comparing a normal WIMP key code
- to the &1000 value for return will fail to work!
-
-
- Contacting the author
- =====================
-
- Any bug reports, suggestions, etc. can be sent to me at:
- jason@cconcepts.co.uk
-
- or snail mail me at Computer Concepts.
-
- If you wish to use this module in a commercial application, it would be a good
- idea to contact me to see if there is a newer version of the module available.
-
-
- Disclaimer
- ==========
-
- Although I now work for Computer Concepts, and this is the only permanent
- contact address I can currently supply, development of/support for WimpKey
- has absolutely nothing whatsoever to do with Computer Concepts
-
- Any enquiries to Computer Concepts about this module will most likely be
- met with a blank, uncomprehending stare, so make sure you ask *me*.
-
-
- Modifications
- -------------
-
- Look at the list for a complete run-down of the various changes made to this
- module. It’s not very drastic at all, just changing the name of some of the
- keys to use the official (and standard) notation as used in the RISC OS 3
- Style Guide: ESC, SPC and DEL become Esc, Space and Delete (looked too much
- like control codes from an EPSON manual ;-) ), and textual equivalents have
- been preferred to ⇦⇨⇩⇧. The first reason is that ⇧ is used for Shift, so
- some of those strings started looking strange (^⇧⇩ for instance, for
- Ctrl-Shift-Down arrow). The second is that Acorn says you shouldn’t do that
- sort of thing because those characters aren’t available in outline fonts;
- the Germans already have outline fonts as standard (lucky bastards :-( ),
- and all rumours say we should be getting them soon (hell, the *Style Guide*
- says there will be outline fonts as standard in the future!). I’m editing
- this file with an outline font, so all those characters look like 4s and
- TMs ;-)
- Anyway, you should all use this module: it’s short, useful, and a
- darn sight better than writing your own code (I did years ago and it was
- massive). My only gripe is that it’s difficult to change the mappings if you
- don’t like the current ones (although as they’re now Style Guide ones, if
- you don’t like them, the official line is “tough!”). You could always
- hand-edit the file I suppose ... but *take a backup first!*.
-