3.1.2.1.1.8 keymap (Key Map Entry)
This element describes an individual key mapping. Its attributes collectively specify a sequence of key combinations that, when pressed, will cause the execution of an action such as a fixed command or macro. The action to execute is described by a single child element. A built-in key mapping can also be blocked.
The key combination for the mapping may be specified using KCM- (key code with modifiers) and CHM- (character with modifiers) based attributes. Both use a set of binary flags for the first (or left) byte to designate the modifier keys for a key combination. Starting at the least significant bit, these take the order Shift, Control, Alt and Command (where the operating system distinguishes between Command and Control). These flags may be used individually or combined. For example, using Control as the only modifier would be represented by 02 (only the second bit is on) while using Control and Alt simultaneously would be 06 (the second and third bits are on).
If a secondary key combination attribute is omitted and a primary key combination has already been defined, the associated action will be executed as soon as the primary key combination has been pressed; otherwise, if both are specified, the action will not execute until both key combinations have been pressed in sequence.
[Example: Consider the following key mapping fragment:
-
<wne:keymap wne:kcmPrimary="0342" wne:kcmSecondary="0441"> <wne:fci … /> </wne:keymap>
In this example, the WordprocessingML describes a mapping
for a sequence of two key combinations given by the KCMs of 0342 and 0441. A KCM of 0342 represents Ctrl-Shift-B and 0441 represents Alt-A, meaning that the user needs to
type Control-Shift-B followed by Alt-A to trigger this mapping's action. The fci child element signifies that a fixed command will
be executed when the specified key sequence is pressed. end example]
|
Parent Elements |
|---|
|
keymaps (§3.1.2.1.1.9, keymaps); keymapsBad (§3.1.2.1.1.10, keymapsBad) |
|
Child Elements |
Subclause |
|---|---|
|
acd (Allocated Command Keyboard Customization Action) |
|
|
fci (Fixed Command Keyboard Customization Action) |
|
|
macro (Macro Keyboard Customization Action) |
|
|
wch (Character Insertion Keyboard Customization Action) |
|
|
wll (WLL Macro Keyboard Customization Action) |
|
Attributes |
Description |
|---|---|
|
chmPrimary (Keyboard Shortcut Primary Character Code) |
Specifies the first CHM key combination in the sequence.
The left byte contains modifiers described in keymap (§3.1.2.1.1.8, keymap) and the right byte specifies the ASCII value of the character of this key combination.
[Note: When specifying CHM values, the case of the letter is significant with respect to shift acting as a modifier or not.]
[Example: Consider this list of example key combinations and their corresponding CHM in parentheses:
Shift-Control-Alt-C (0643) Alt-C (0463) Control-K (026B)
end example]
The possible values for this attribute are defined by the ST_ShortHexNumber simple type (§3.1.2.3.4, ST_ShortHexNumber). |
|
chmSecondary (Keyboard Shortcut Secondary Character Code) |
Specifies the second CHM key combination in the sequence.
The CHM value here is defined the same as for chmPrimary.
The possible values for this attribute are defined by the ST_ShortHexNumber simple type (§3.1.2.3.4, ST_ShortHexNumber). |
|
kcmPrimary (Primary keycode with modifier) |
Specifies the first key combination in the sequence.
The left byte contains modifiers described in keymap (§3.1.2.1.1.8, keymap), and the right byte specifies the standard Windows virtual key code of this key combination.
[Example: Consider this list of example key combinations and their corresponding KCM in parentheses:
Shift-Control-Alt-C (0743) Alt-F9 (0478) Control-K (024B)
end example]
The possible values for this attribute are defined by the ST_ShortHexNumber simple type (§3.1.2.3.4, ST_ShortHexNumber). |
|
kcmSecondary (Secondary keycode with modifier) |
Specifies the second key combination in the sequence.
The KCM value here is defined the same as for kcmPrimary.
The possible values for this attribute are defined by the ST_ShortHexNumber simple type (§3.1.2.3.4, ST_ShortHexNumber). |
|
mask (Built-in Command Masking Flag) |
If this Boolean attribute is set to an on value, the specified built-in key mapping will be masked out. In such a case, any child element specified shall be ignored because the masking of a key mapping does not involve specifying either a replacement action or the action being blocked. If this attribute is omitted or given an off value, a child element must be specified or the key map will be ignored.
[Example: Consider the case where Control-B (the built-in key mapping for the Bold fixed command) has been masked:
KCM 0242 has been masked or blocked from its built-in behavior. The effect is that pressing Control-B will no longer execute the built-in command (in this case bold). end example]
The possible values for this attribute are defined by the ST_OnOff simple type (§3.1.2.3.3, ST_OnOff). |
The following XML Schema fragment defines the contents of this element:
-
<complexType name="CT_Keymap"> <choice minOccurs="0" maxOccurs="1"> <element name="fci" type="CT_Fci"/> <element name="macro" type="CT_MacroWll"/> <element name="acd" type="CT_AcdKeymap"/> <element name="wll" type="CT_MacroWll"/> <element name="wch" type="CT_LongHexNumber"/> </choice> <attribute name="chmPrimary" type="ST_ShortHexNumber"/> <attribute name="chmSecondary" type="ST_ShortHexNumber"/> <attribute name="kcmPrimary" type="ST_ShortHexNumber"/> <attribute name="kcmSecondary" type="ST_ShortHexNumber"/> <attribute name="mask" type="ST_OnOff"/> </complexType>