Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d6xx/d642/editkeys.lha/EditKeys/EditKeys.Doc

Text File | 1992-04-26 | 21KB | 457 lines

                EditKeys v1.2
                -------------

                 © 1991 David Kinder
                 -------------------

Introduction
------------

About a year ago, I was trying to find a program to allow me to edit the
system keymap files. There were a few that let you put strings on keys, but
none gave total control over all the features of keymaps. So I decided to
write my own editor. I mean, how hard could it be..?

The result is EditKeys, a keymap editing program designed to work under
both AmigaDOS 1.3 and 2.0. EditKeys is written in machine code and compiled
using HiSoft's Devpac v3 assembler, though it should not be that difficult
to compile under other assemblers. EditKeys is freely distributable,
provided that no more is charged than a nominal fee for copying and disk
media. If you want to use a keymap created with EditKeys in a PD or
commercial package then the only condition I impose is that I receive a
credit somewhere in the program or its documentation.

Files
-----
    Program     - EditKeys
              EditKeys.info
    Documentation    - EditKeys.Doc
    Disk Library    - arp.library (must be in LIBS: if you
                       are using AmigaDOS 1.3)
    Source files    - EditKeys.s
              Graphics.s
              xdef.i
              xref.i

About EditKeys
--------------

EditKeys allows you to edit or create keymap files (They are found in the
devs/keymaps/ directory of the system disk, which is only accessible from
the CLI; there are no Workbench icons). If you don't know about these files,
then perhaps I should explain.

When you press a key on the Amiga's keyboard, the key press is translated by
the keymap file that the system is using (This will probably be 'gb'; the
following assumes you are using a British Amiga). To see the effect of a
keymap, boot with a standard 1.3 system disk, open a CLI window then type

    SYS:System/SetMap usa1

Now press the key marked with a hash '#'. Instead of the hash you expect, you
get an apostrophe (which is what an American user would expect from that
key).

A British 1.3 system disk contains two keymaps; 'gb' and 'usa1'. More keymaps
can be found in the devs/keymaps/ directory of the Extras disk.

More radical changes to the keys could be made; you could redefine the
numerical keypad to produce alphabetic characters if you wanted to, or you
can configure keys to output strings (useful for disk-menus etc.).

Please note that any changes made using EditKeys do NOT come into effect
until you enter the SetMap command at the CLI prompt; only when you select
'Save' in EditKeys is a suitable keymap structure constructed and saved to
disk so that the Amiga OS can use it.

Keymap Specifications
---------------------

At this point, perhaps I should define some of the terms I will use:

  Qualifier Key - CTRL, ALT or SHIFT keys. Do not produce output on their
          own but qualify the output of other keys (eg Shift-f
          produces 'F').

  Physical Key    - An actual key on the keyboard, the thing that you touch
          when you type.

  Key        - A combination of a physical key and a qualifier, eg q is
          a key, as is Shift-q, Alt-q, Shift-Alt-q, etc. Note that
          Alt-q is an abreiviation for holding down the ALT key
          while tapping the 'q' key.

Keymaps contain quite a lot of information, none of which appears in the user
manuals but appears in the RKM under 'console.device' (Makes sense to put
info about the keyboard in a programmer's manual eh?). Therefore I shall
attempt to briefly describe what is possible.

Keys can be redefined to produce any character when pressed with one of the
qualifiers, and also keys can produce strings of up to 32 characters.
Physical keys with a STRING key on them may not have DEAD or MODIFIABLE keys
on them (see below).

Some keys repeat when held down (eg all alphabetic keys), while others do not
(eg the <RETURN> key). Physical keys which repeat are referred to as
REPEATABLE (fairly obvious). Whether a key repeats or not is controlled by
the keymap. Similarly, the keymap controls whether a key is CAPSABLE or not.
When the 'Caps Lock' light is on, some keys produce their Shifted values (eg
'q'), while the numerical keys produce their normal values.

Some keys are DEAD, while others are MODIFIABLE. For an example of this, open
a CLI window, then hold down ALT while tapping the 'f' key (From now on
abrieviated to Alt-f); nothing happens. Now tap the 'a' key, the result is
an a with an accent over it: 'á'. The key Alt-f is a DEAD key, while 'a' is a
MODIFIABLE key. When you type Alt-f, the Amiga stores the deadkey, which it
then uses to modify the output of the 'a' key. Not all keys are MODIFIABLE,
Alt-f followed by 'q' just produces 'q'. A physical key with DEAD or
MODIFIABLE keys on it may NOT have STRING keys on it.

There is a further limitation in that those physical keys that are not DEAD
or MODIFIABLE use only 4 bytes for their definition, eg on the 'A' key on
your keyboard there is 'a', 'A', 'æ' and 'Æ'. However, there are 8 different
permutations of the Shift, Alt and Control qualifiers with the key, so not
every combination of physical key with qualifier can be uniquely defined.
Why didn't Commodore use 8 bytes for each key??? (sigh). There is one other
point; if a physical key has definitions for Shift and Alt (and thus
Shift-Alt) then we can configure the key so that the Control qualifier
outputs the value that would appear without the Control key being pressed,
but with bits 6 and 7 cleared (eg Control-c). Confused? You're not the only
one... But playing around with EditKeys should make all this clear (or at
least clearer than it is at present).

To install a keymap in the system, you use the 'SetMap' program found in the
System drawer of a standard Workbench disk. It is worth noting before I start
on a discussion of EditKeys that once you have loaded a keymap into AmigaDOS
with SetMap, it will not flush it from memory until you reboot (this is
because the system expects keymaps not to change). So if you used say
'SetMap gb' (as in a UK Startup-Sequence), then edited 'gb' using EditKeys
and reissued a 'SetMap gb' command at the CLI, then you would not get your
new keymap, as the system would just use the version of 'gb' loaded first. To
get around this simply save the edited keymap under a new name eg. 'gb2'.
Furthermore, a keymap should have its name embedded in it, so if you rename
a keymap EditKeys will no longer believe that it really is a keymap (although
it will still work with the 1.3 SetMap command).

The Program
-----------

EditKeys allows you to modify all the above features of a keymap. Keys may be
made DEAD or MODIFIABLE, or have STRING definitions put on them, as well as
being redefined. The program may be started from CLI or Workbench:

From Workbench: Just double click on the program's icon. A file requester
        will appear for you to select a keymap to load. Click on
        a keymap or 'Cancel'.

From CLI:    1) Just type the program's name, ie

            1> EditKeys

        The program will attempt to display a file requester
        prompting you for a keymap to load. Select a keymap or
        click on 'Cancel' to start the program without a keymap
        loaded. Or,

        2) Pass a keymap name to the program, ie.

            EditKeys [<keymap>] [NOMAP]

           eg    1> EditKeys gb
           or    1> EditKeys NOMAP

        You do not need to specify the path of the keymap as EditKeys
        will automatically look in DEVS:keymaps/. If you specify the
        NOMAP option then EditKeys will start without loading a
        keymap. Or,

        3) Enter the line

            1> EditKeys ?

        Which will bring up a template. Entering a further ? will
        prompt you with a small help message. Enter a keymap name
        or NOMAP (see above).

When the program has loaded it will open a window on the Workbench screen.
In the titlebar is the name of the keymap being edited; below that is a
representation of the A500/A2000 keyboard with the keymap you chose. Note
that it may appear to you that the keyboard has acquired two extra keys
(one to the right of the left Shift key and the other to the left of the
Return key), but the Rom Kernel Manual assures me that they are on all
keyboards except UK and American ones...

Furthermore, the representation of the keymap usually shows what is output
by that key, but for certain keys (eg Esc, Help, Del, F1-F10) I have chosen
to use a little graphic which never changes as this looks better. If you need
to be certain what a key outputs, click on it; its output will be displayed
at the bottom to the EditKeys window.

Qualifier keys (Shift etc.) displayed on the screen work as expected; click
on Shift to see the effect. The program is run using the menu and the five
mode gadgets displayed below the keyboard; each gadget represents a different
aspect of the keymap that can be edited. To choose a mode, simply click on
its gadget. The five modes are:

    KeyMap       - Used to (re)define output of any key
    Capsable   - Used to determine which keys are capsable
    Repeatable - Used to determine which keys repeat
    Modifiable - Used to define which keys are modifiable
    Deadkeys   - Used to define dead keys

I will deal with these sections in increasing order of complexity.

Capsable
--------

As explained above, physical keys can be CAPSABLE or not, and this mode lets
you set this function for each physical key. If the key is highlighed then
that key is capsable; if it is not then the physical key isn't. The qualifier
gadgets are ghosted as they serve no purpose in this mode. Simply click on a
key with the mouse to change it's state.

Repeatable
----------

Basically the same as the above Capsable mode, except that this mode is used
to control which keys are REPEATABLE or not. Works in exactly the same way as
above.

Deadkeys
--------

As expained above, keymaps can contain DEAD keys, and this mode allows you to
set them. Click on a key to make it dead or turn it back to normal. Deadkeys
don't do anything immediately when pressed; thus when you turn a dead back to
normal the key is blank. Since each particular key can be DEAD or not, the
qualifiers are active.

If you make a key dead, and the physical key that key is on already has
another deadkey, then you can make the second deadkey act in the same way as
the first. This isn't too useful, but it's implemented in the CBM keymaps, so
here it is.

Deadkey definitions are stored within the keymap in a completely diffent way
to ordinary keys, so if a physical key has deadkeys on it, then it can be
defined for any combination of qualifiers. As expained earlier, this is not
so for ordinary keys. If you turn a deadkey back to normal and it is the last
deadkey on that physical key, EditKeys will try to resolve this without
destroying any definitions; but if it can't a requester will appear asking
you which definitions you want to get rid of. As a general rule the least
useful set of definitions are those with the Control qualifier, so I'd remove
these first if I were you, but it's your choice. As also explained above, if
a normal key has definitions for Shift, Alt and Shift-Alt, then the Control
key may have a special effect on it - it may clear bits 6&7 of the normaly
output character (eg if you enter Control-c in the string gadget, you get
a capital C in reverse (try it and see)). If it is possible to do this with
the key as we convert it from dead to normal, a requester will appear asking
whether you want this feature or not (As a general rule, in the CBM supplied
keymaps it is turned on for most alphabetic keys).

You can have a maximum of 15 deadkeys, a limitation imposed by the keymap,
not me. 15 should be enough anyway. If you define 15 diffent deadkeys then
all non-dead keys will be ghosted as no more can be defined. Turn a deadkey
back to a normal key to de-ghost all the other keys. Physical keys with
STRING keys on them cannot also have DEAD keys on them; thus all string keys
are ghosted and unselectable. Physical keys with MODIFIABLE keys on them may
also have DEAD keys on them.

Modifiable
----------

This mode works in exactly the same way as the above 'Deadkeys', except that
it allows you to select which keys are MODIFIABLE. Note that I have imposed
an arbitrary limit of 256 modifiable keys in any one keymap, but I doubt that
you would ever need anything like this figure.

KeyMap
------

This is the mode you will probably most often use; it allows you to redefine
what each key outputs when pressed. Since this bit is quite complex, I'll
split it into several sections.

Click on the qualifiers and a key to select which key you want to edit. The
selected key will appear highlighted (ie yellow lettering on a black
background), and the cursor in the string gadget below the keyboard will
activate. If you now type something, it will appear in this gadget (since it
is just an Intuition string gadget you can also just click inside it to
re-activate it). There are various types of keys in a keymap (as detailed
previously) so I shall explain how the editing fuctions affect each one:

Deadkeys    - Since deadkeys do not output anything themselves but change
          the output of other keys, you cannot edit a deadkey and so
          such keys are ghosted in this mode. However they are used
          in conjuction with modifiable keys (see section below).
          Since physical keys with deadkeys on them may also have
          keys that work normally (eg Alt-f is a deadkey; Shift-f and
          f just work as normal) such keys (eg f) can be edited as
          detailed below with the restriction that such keys may NOT
          have strings on them.

Ordinary keys    - This is the majority of keys, which have no special
          features (eg deadkeys). When you click on such a key, the
          character output by this key will appear in the little box
          to the left of the string gadget below the keymap.

          If you enter a single character into the string gadget,
          then this will become the character output by the selected
          key, and the picture of the keymap will change to reflect
          this. As not all combinations of qualifier and physical key
          can be uniquely redefined, at certain times (especially if
          you edit a key with the Control qualifier (eg Control-q)) a
          requester will appear telling you that some definitions
          will have to be lost in order to allow your editing, and
          giving you the option of aborting or letting EditKeys
          remove some of the other definitions on that physical key.

          Futhermore, the combination of Shift-Alt-Control-key cannot
          be defined at all for ordinary keys. If you try this
          EditKeys will tell you that this is not possible.

          If you enter more than one character into the string
          gadget, EditKeys will convert that key into a STRING type
          key (see below).

Modifiable keys - Modifiable keys (eg a) can have their output modified by
          deadkeys (eg Alt-f followed by a produces á). Such keys
          can be edited as above except that strings are not
          permissible on such keys, thus you can redefine what 'a'
          outputs. But what if you want to redefine what Alt-f
          followed by 'a' outputs?

          If you double click the right mouse button, a requester
          titled 'Select deadkey' will appear. This allows you to
          choose a deadkey to be used in editing modifiable keys.
          The requester has gadgets to accept the current deadkey,
          quit without changing anything, or clearing the current
          deadkey. To select a deadkey simply type it in at the
          keyboard (eg hold down Alt and press f). The text 'A-f'
          will appear in the box. Enter another deadkey if you want
          to change or press the 'Clear' gadget if you don't want to
          use a deadkey anymore, then click 'Use this deadkey'. The
          name of the deadkey (eg A-f (which is short for Alt-f))
          will now appear in the far left box at the bottom of the
          EditKeys window. Now click on a modifiable key (eg a) and
          the character output by the combination of the selected
          deadkey and the selected modifiable key will appear in the
          box to the left of the string gadget (if you are using my
          example an 'á' will appear there). Now when you enter a
          character into the string gadget will edit what is output
          by the combination of the selected deadkey and the selected
          modifiable key. Try it - it is fairly obvious once you're
          used to it.

String keys    - Lastly, string keys. If you click on a string key (or
          change an ordinary key into one by entering more than one
          character into the string gadget) then the box to the left
          of the string gadget turns yellow. String keys may be
          edited in the normal way, except that you may enter up to
          32 characters to be output by each key (Some keymaps seem
          to have more than this, but the RKM seems to suggest 32 is
          the safe limit for the console buffer, so 32 it is).

          Note that string keys are usually displayed by EditKeys on
          its picture of the keymap as the letters 'STR' where
          possible (eg 'Help' is a string key but it always appears
          as 'Help' in the little picture as this looks neater).

          If you edit a physical key with strings on it so that each
          string is only one character, EditKeys will give you the
          option of converting that physical key back to an ordinary
          key (which saves memory). As usual, EditKeys may have to
          remove some definitions to accomodate this; a requester
          will appear to warn you if this is the case.

          Note that if at any time you want to put a carriage return
          in a string, use control-m (a reversed M will appear in the
          string gadget). This is useful for eg. putting common CLI
          commands on function keys. Thus, if you put

            list*

          (where * represents control-m) on F1, then with this keymap
          in use via SetMap, pressing F1 will send a list command to
          the CLI as if you had typed it in and pressed <RETURN>.

There is one further point - to the right of the string gadget is a gadget
marked <CSI>. What does this mean? Well, if you click a key such as F1 (with
a standard CBM keymap loaded), you will get something like *0~ where * is a
little square box. This box is used for characters that are not specifically
defined for that font, and in this case the character is $9B hex, which is
known as the 'Control Sequence Inducer', or <CSI> for short. <CSI> is used to
indicate that what follows is not to be output directly but is to be
interpreted by the Amiga to eg. change the text colour etc. There are too
many sequences to document here (they are in the RKM under 'console.device').
Since you can't enter the character $9B directly using a CBM keymap, clicking
the <CSI> gadget puts this character as the first character in the string
gadget, from there there it behaves as any other characater.

The Menu
--------

The remaining functions of EditKeys are accessed through the pull-down
menu. These are:

New    - Completely clears all information from EditKeys, so allowing you
      to create a keymap completely from scratch (but believe me, it's
      easier to edit an existing one!).

Load    - A file requester appears to allow you to select a keymap to load
      in. Note that the keymap does not have to be in DEVS:keymaps/ for
      to you to be able to load it in.

Save    - Saves the current keymap. The keymap is saved to the name of the
      keymap last loaded. Note that any previous keymap of the same name
      is overwritten (so be carefull!!).

Save As - A file requester appears to allow you to select the filename that
      you wish the current keymap to be saved to. Again, you do not need
      to save to the DEVS:keymaps/ directory, but if you don't, you won't
      be able to SetMap the keymap without moving it elsewhere or playing
      around with the Assign command.

About    - Guess.

Sleep    - Since the EditKeys window is rather large, you can use this option
      to shrink EditKeys out of the way. Under AmigaDOS 1.3, EditKeys
      opens a tiny window with just one gadget in it. Click on this
      gadget to make EditKeys reopen its main window and resume normal
      operations.
      Under AmigaDOS 2.0, this option closes the main EditKeys window
      and adds an 'EditKeys' menu item to the Workbench Tools menu. If
      you select this item EditKeys will restart.

Quit    - Guess... A requester checks that you are sure before quiting (any
      unsaved keymaps will be lost if you quit!).

Well, I think that's it. I think (hope!) the program is easier to use that
this file is to understand, so just use EditKeys and all should become clear.

If for any reason you want to contact me about EditKeys, the address is

      David Kinder,
      28, Langholm Rd.,
      Garswood,
      Ashton-in-Makerfield,
      Lancs.
      WN4 0SG.
      ENGLAND.

History
-------

v1.0      First release.

v1.1      Improved appearance under AmigaDOS 2.0.

v1.2      Removed need for 'arp.library' under AmigaDOS 2.0.
      Renamed 'Iconify' menu option to 'Sleep' to reflect that with
      AmigaDOS 2.0 'Sleep' closes EditKeys down to an item in the
      Workbench Tools menu.


      "Rise and Reverberate"