Skip to content

Commit 9ab0ae6

Browse files
BGPierceBGPierce
authored
Merge pull request #91 from ejaquay/main
Merge and update custom keymap document.
2 parents 015ba94 + bc763c8 commit 9ab0ae6

File tree

1 file changed

+109
-96
lines changed

1 file changed

+109
-96
lines changed

‎docs/KeyMapEditor.txt‎

Lines changed: 109 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,74 @@
11

2-
Vcc KeyMap Editor
3-
Description of operation
2+
Vcc Keyboard Configuration and Key Mapping
43

5-
The Vcc key map editor consists of two main components; the Vcc
6-
Custom Keyboard Map file and the Edit Custom Key Map dialog.
7-
These are discussed below.
4+
Keyboard Layout
5+
---------------
86

9-
Vcc Custom Keyboard Map File
10-
----------------------------
7+
The default VCC keyboard layout tries to resemble the physical layout of
8+
the Color Computer 3 keyboard. This works well with Disk Extended Color
9+
Basic (DECB) but not so well with the more powerful OS-9 and NitrOS-9
10+
operating systems. Also some PCs do not have number pads or have uncommon
11+
layouts. For these reasons VCC provides three built-in keyboard layouts
12+
(CoCo, Natural, Compact) and a user modifyable Custom layout.
1113

12-
The keyboard map file is used to map host PC key codes into Color
13-
Computer 3 keys. This file has the default name "custom.keymap" and
14-
resides in the user's Vcc appdata directory. The file contains
15-
lines of text and can be edited using Notepad if that is desired.
14+
The Coco (DECB) layout maps the PC’s keyboard in a layout similar to an
15+
actual Coco 3 keyboard.
1616

17-
Each line contains four fields (two pairs) seperated by one or
18-
more spaces or tabs. Blank lines, lines starting with "#",
19-
or anything on a line beyond four fields are comments. The first
20-
two fields on each non-comment line are the PC code and it's
21-
modifier. The second two fields are the CoCo key and it's
22-
modifier.
17+
Natural (OS-9) maps the PC’s keyboard is to match the keycaps on a US
18+
QWERTY keyboard with the exception of a few special keys.
2319

24-
PC keynames start with "DIK_" and CoCo key names start with
25-
"COCO_". Key modifiers are specified with a single digit as
26-
follows:
20+
Compact (OS-9) is simular to Natural, but with some keys altered to
21+
compensate for missing the number pad keys on smaller laptops.
2722

28-
0=not modified, 1=shift, 2=control, 3=alt.
23+
See the “VCC Keyboard Map” section for details of the build-in key
24+
mappings.
2925

30-
A list of valid PC and CoCo key names can be found in keynames.h
31-
in Vcc sources.
26+
The Custom layout is stored in a seperate file while the built-in layouts
27+
are hardcoded within the VCC executable.
28+
29+
The current layout is selected in the Keyboard tab on the Configuration menu.
30+
From there click the radio button for the desired layout and click OK
31+
or Apply.
32+
33+
Also on the Configuration Keyboard tab there is a section that allows the
34+
Custom keyboard mapping to be configured.
35+
36+
Use the "Choose File" button to change the custom keymap file. If the chosen
37+
file exists the keymap is loaded. If the file does not exist a new file is
38+
created containing the previously selected keymapping. This allows user to
39+
create a new file that contains a copy of either one of the built-in keymaps or
40+
the current custom map.
41+
42+
Use the "EDIT" button to modify the current custom keymap using keymap editor.
43+
Changes made in the keymap editor take immediate effect and are automatically
44+
saved to the choosen keymap file. (Unless Cancel is selected within the Editor)
45+
46+
Using either the "Choose File" or the "EDIT" functions will cause the Custom
47+
keymap to be automatically selected.
48+
49+
It is possible to modify keymap files using notepad or a text editor. This
50+
should only be done for keymap files not currently choosen while VCC is
51+
running. Otherwise VCC will overwrite the changes.
52+
53+
54+
Custom Keyboard Map File
55+
------------------------
56+
57+
The keyboard map file is used to map host PC key codes into Color Computer 3
58+
keys. This file has the default name "custom.keymap" and resides in the user's
59+
Vcc appdata directory. The file contains lines of text, each contains four
60+
fields (two pairs) seperated by one or more spaces or tabs. Blank lines,
61+
lines starting with "#", or anything on a line beyond four fields are comments.
62+
All other lines are key definitions. The first two fields of a key definition
63+
are the PC code and it's modifier. The next two fields are the CoCo key and
64+
it's modifier.
65+
66+
PC keynames start with "DIK_" and CoCo key names start with "COCO_".
67+
Key modifiers are specified with a single digit as follows:
68+
69+
0=not modified, 1=shift, 2=control, 3=alt.
70+
71+
A list of valid PC and CoCo key names can be found in keynames.h in Vcc sources.
3272

3373
Here are some example entry lines:
3474

@@ -37,78 +77,51 @@ Here are some example entry lines:
3777
DIK_EQUALS 0 COCO_MINUS 1 # "=" Coco
3878
DIK_MINUS 1 COCO_MINUS 2 # "_" NitrOS-9
3979

40-
This above example maps the "Equals" key on the host PC to
41-
"Shift" + "-" keys in Vcc and the "Shift" + "-" keys on the
42-
host PC keyboard to "Alt" + "-" keys in Vcc. This matches
43-
what is printed on the keycaps of many keyboards with what
44-
the CoCo uses.
45-
46-
The file contents are loaded into Vcc when the KeyBoard Mapping
47-
is changed to "Custom" in the Vcc Options "Keyboard" tab dialog.
48-
If the file does not exist Vcc will use default values for the
49-
custom keymapping. In this later case the "Select File" function
50-
in the Edit Custom Key Map Dialog can be used to generate the
51-
file.
52-
53-
Any CoCo key that is not mapped in the keymap file will be
54-
"dead" in Vcc. However shifted letter keys do not need to be
55-
mapped to make them uppercase because DECB and NitrOS-9 will
56-
handle this internally.
57-
58-
Whenever Vcc updates the keymap file all comments after the first
59-
valid map entry will be removed. This means user comments should
60-
be confined to the head of the file. Also entry order may be
61-
changed by the Edit Custom Key Map dialog.
62-
63-
Edit Custom Key Map dialog
80+
This above example maps the '=' PC key to the 'Shift+' CoCo keys and 'Shift-'
81+
PC keys to 'Alt-' CoCo keys in Vcc.
82+
83+
Any CoCo key that is not mapped in the keymap file will be dead in Vcc.
84+
However shifted letter keys do not need to be mapped to make them uppercase
85+
because both DECB and NitrOS-9 will handle this internally.
86+
87+
It is important to note that some PC keys can not be mapped. Specifically the
88+
F3-F11 keys can not be mapped, they are used for Vcc control. Keys selected
89+
for joystick input via the Joysticks config tab can not be mapped. Adding
90+
mappings for any of these keys in the keymap file will have no effect. Also
91+
the both Right Shift and Right Control keys are automatically mapped to match
92+
their left counterparts so they can not be independantly mapped.
93+
94+
Whenever Vcc updates the keymap file all comments after the first valid map
95+
entry will be removed. This means user comments should be confined to the head
96+
of the file. Entry order may be changed by the Edit Custom Key Map dialog.
97+
98+
Edit Custom Key Map screen
6499
--------------------------
65100

66-
The edit key map dialog is activated by clicking the EDIT button
67-
in the Vcc Options "Keyboard" tab dialog. The dialog has a virtual
68-
Color Computer 3 keyboard, a file name text box, a CoCo Key text
69-
box, and Host Key text box, and the following buttons:
70-
71-
"Save Keymap" Used to save key map modfications to keymap file
72-
"Select File" Used to select the keymap file to use.
73-
"Set" Used to modify a key mapping in Vcc
74-
"Clear" Used to clear out the CoCo and Host text boxes
75-
"Exit" Used to exit the dialog.
76-
77-
Other than selecting which PC key and modifier to map the dialog
78-
can not be navigated using the PC keyboard. Buttons can only be
79-
activated with a pointing device or touch keyboard.
80-
81-
Once the dialog is entered pressing any key on the PC keyboard will
82-
cause the corresponding key button on the virtual CoCo keyboard to
83-
be pushed in and text describing the keys to appear in the CoCo
84-
Key and Host Key text boxes. If the PC key has no mapping the
85-
CoCo key text box will be blank and no button on the virtual CoCo
86-
keyboard will be pushed. Keys toggle - if the same key is pressed
87-
twice it toggled on-off. Modifier keys can be toggled either
88-
before or after non-modifier keys. This functionality allows user
89-
to quickly toggle through various PC key combinations to see the
90-
Vcc mapping of each.
91-
92-
To change a keymapping user first selects a PC key and optional
93-
modifier by the above method and then clicks on a key button(s)
94-
on the virtual CoCo keyboard. This causes the "Set" button to
95-
become active. One the desired keymapping is seen clicking the
96-
"Set" button commits the mapping to Vcc. If instead the "Clear"
97-
button is clicked or any PC key is pushed the "Set" button will
98-
be deactivated and the keymap change is canceled.
99-
100-
Changing the mapping of a key by the above method is temporary
101-
until the change is saved to the keymap file using the
102-
"Save Keymap" button (which activates if the keymap has been
103-
changed). It is considered normal to leave the Edit Key Map
104-
dialog without saving a map change. This allows user to use
105-
the change for the duration of the session without having it
106-
be permanant.
107-
108-
The keymap file name can be changed with the "Select File" button.
109-
Pressing this button brings up an open file dialog which allows
110-
user to choose a different keymap file. When a file is selected
111-
the current custom keymapping is automatically saved to it. If
112-
the file selected does not exist the user is prompted if they
113-
want to create it.
114-
101+
The Edit Custom Key Map screen is activated by clicking the "EDIT" button on
102+
the configuration menu Keyboard tab. The screen shows a virtual CoCo 3
103+
keyboard, a Host Key text box, a Coco Key text box, and three buttons:
104+
105+
"Apply" To apply an individual key modfication.
106+
"OK" To save the changes and exit the editor.
107+
"Cancel" To undo changes and exit the editor.
108+
109+
Pressing a key on the PC keyboard causes it to be shown in the "Host Key" text
110+
box and if the key is mapped that will be shown in the "CoCo Key" text box
111+
and the key on the virtual keyboard to appear as pressed. Pressing a different
112+
PC key (other than a modifier) deselects the previous key and selects the new
113+
one. Modifier keys can be toggled either before or after non-modifier keys.
114+
This functionality allows easy toggling through various PC key combinations
115+
to see the CoCo mapping of each.
116+
117+
Mouse clicks (or touch on a touch screen) on the virtual keyboard are used
118+
to modify the PC key mapping. The Shift, Alt, and Control modifier keys can
119+
be combined with the PC or CoCo keys being pressed. Clicking a key button
120+
when no PC key is selected causes an warning popup to be issued.
121+
122+
Once a key mapping is changed the "Apply" button is enabled. Pressing either
123+
the "Apply" or the "OK" button sets the new mapping. "OK" exits the editor
124+
so "Apply" should be used if more than one key is to be mapped. All changes
125+
are automatically saved to the keymap file when "OK" is pressed and are
126+
discarded if "Cancel" is.
127+

0 commit comments

Comments
 (0)