KEYBINDINGS_SECTION – KEYBINDINGS_END
Note
Beginning with Visual Studio 2008 SDK, use XML Command Table (.vsct) files instead of command table configuration (.ctc) files to define how menus and commands appear in your VSPackages. For more information, see XML-Based Command Table Configuration (.vsct) Files.
The KEYBINDINGS_SECTION – KEYBINDINGS_END section of a command table configuration (.ctc) file specifies the mapping of commands to key combinations. Such a mapping is also known as a key binding.
Commands can have both single and dual key bindings. An example of a single key binding is CTRL+S to trigger the save command. Dual key bindings, or chords, require two key combinations to be pressed successively to trigger a command. An example of a dual key binding is CTRL+K CTRL+K to set a bookmark.
The Keybinding Entry
Each entry in the KEYBINDINGS_SECTION – KEYBINDINGS_END section must contain values for four fields: Command ID, Editor ID, Emulation ID, and Key State. These fields are described in the following table.
Field |
Description |
|---|---|
Command ID |
A GUID:ID pair identifying the command that the key combination is bound to. |
Editor ID |
A command UI context GUID (CmdUIGUID) identifying the editor in which the key combination is available. If the editor has a single view or tab, the GUID should be the same as that of the editor. If the editor has multiple tabs or views, use a value of either guidVSStd97 or GuidKeyDupe. |
Emuluation ID |
A GUID identifying the keyboard emulation in which the key binding is available. The Emulation ID field is reserved for future use. For the present, it should be set to the same value as Editor ID. |
Key State |
Specifies the key combination that triggers the command. |
As shown in the example below, the field values in each entry must be entered in order and separated by commas, and the entry must end with a semi-colon.
For more information about fields and values, see "The Keybinding Entry Fields" later in this topic.
Keybinding Example
The following example from the .ctc file in the Basic Edit sample shows some key binding entries. In this particular situation, the Basic Editor is overriding existing commands in the integrated development environment (IDE), which have been specified in the CMDUSED_SECTION - CMDUSED_END section.
KEYBINDINGS_SECTION
// GUID:CMDID EDITORGUID EMULATIONGUID KEYSTATE
guidVSStd97:cmdidBold, guidBscEdtEdtr, guidBscEdtEdtr, 'B':C;
guidVSStd97:cmdidBold, guidBscEdtEdtr, guidBscEdtEdtr, 'B':CS;
guidVSStd97:cmdidItalic, guidBscEdtEdtr, guidBscEdtEdtr, 'I':C;
guidVSStd97:cmdidUnderline, guidBscEdtEdtr, guidBscEdtEdtr, 'U':C;
guidVSStd97:cmdidJustifyLeft, guidBscEdtEdtr, guidBscEdtEdtr, 'L':C;
guidVSStd97:cmdidJustifyCenter, guidBscEdtEdtr, guidBscEdtEdtr, 'E':C;
guidVSStd97:cmdidJustifyRight, guidBscEdtEdtr, guidBscEdtEdtr, 'R':C;
guidVSStd2K:ECMD_INSERT, guidBscEdtEdtr, guidBscEdtEdtr, VK_INSERT:;
KEYBINDINGS_END
The Keybinding Entry Fields
The fields, in order, are:
Command ID
The Command ID field identifies the command to which you want to assign a key binding. For example, "guidVSStd97:cmdidItalic."
Editor ID
The Editor ID field identifies the scope in which the key binding will be available. The value of Editor ID is a GUID that corresponds to a CmdUIGUID that was assigned by the developer when the editor is created. This Editor ID GUID value may or may not be the same as the GUID for the EditorFactory for the editor.
The default CmdUIGUID of an editor is returned by the pguidCmdUI parameter of the CreateEditorInstance method. The CmdUIGUID of the window is updated by setting the VSFPROPID_CmdUIGuid property on the IVsWindowFrame of the window.
Note
After changing the VSFPROPID_CmdUIGuid property you must call OnElementValueChange with parameter values (SEID_DocumentFrame, FALSE, varWinFrame) to cause new key bindings, toolbars, and so forth to take effect.
An editor with only one view has only a single cmdUIGUID. An advanced editor, however, might have multiple views, or tabs. For example, an HTML editor might have a graphical view and an HTML source text view. If your editor has multiple views, then each view has its own unique CmdUIGUID and can have its own key bindings. To limit the scope of a key binding to only one of the editor's views, set the Editor ID value to the CmdUIGUID of that view.
Key bindings also can be set to the global scope, which means that they apply at all times. To define key bindings at the global scope, use an Editor ID value of guidVSStd97. If you are creating a duplicate binding of an existing globally-scoped command, then use a value of GuidKeyDupe instead. A duplicate binding adds your binding as an alternative to the existing one, but the existing binding takes precedence.
Emulation ID
The Emulation ID field is for reserved for future use. For the present, it should be set to the same value as Editor ID.
Key State
The Key State field specifies the keyboard key combinations that a user can press to trigger a command. The format of each entry is:
Key:Accel : Key:AccelIn the entry, the value of Key must be one of the following:
A literal value, which is the key's letter or number in single quotes. For example, 'A', 'X', or '3'. The Command Table Compiler converts the quoted characters to scan codes. Note that letters should be specified in uppercase even if the Shift key modifier is not applied to the key.
A numerical value, which is the key's decimal or hexadecimal virtual-key code. For example, 32 (decimal for the space), 0x3d (hexadecimal for the equals sign, '='), or 91 (decimal for the open square bracket, '[').
For a list of standard virtual-key codes, see the Winuser.h file in the Platform SDK.
Note
The Command Table Compiler does not convert non-alphanumeric characters, such as '.' or '+', to scan codes. Therefore, characters other than numbers and letters cannot be entered as literals.
The value of Accel specifies a keyboard modifier, a combination of one or more of the following letters or nothing at all (in which case, you must still specify the colon separating Key from Accel):
A = ALT
S = SHIFT
C = CONTROL
For example:
For a single key binding such as CTRL+ALT+X, specify 'X':CA or 75:CA.
For a dual key binding such as CTRL+K CTRL+X, specify 'K':C : 0x4B:C (0x4B is 'X').
For a single key binding with no modifiers, such as Insert, specify VK_INSERT: or 0x2D: (note the trailing colon with nothing after it).
If you specify a second key binding to a command that is already bound, the value in the Editor ID and Emulation ID fields should be set to GUIDKeyDupe. This allows the command to be executed by both bindings.
The Environment Keyboard and VSPackage KEYBINDINGS
The combined key bindings supplied by the Visual Studio environment and all installed VSPackages are considered to be the default key bindings. The user can make changes to the key bindings, and these changes are layered on top of the default bindings. Any key binding a user specifies takes precedence over the default key binding if there is a conflict.
If the user clicks the Reset button in the Keyboard category of the Options dialog box (available from the Tools menu), all of the user's bindings are removed and the default bindings from the installed VSPackages and the environment are restored.
Each time devenv.exe /setup is executed, the default key bindings are recreated from all VSPackages and the environment but the user's key binding changes are not touched. If, as a result of executing devenv.exe /setup, a command the user had bound to a key is no longer available, the user's key binding is simply ignored.
If two VSPackages define the same key binding for different commands, the first VSPackage that is processed during devenv.exe /setup gets the key binding. Because there is no effective way to determine the order in which VSPackages are processed during devenv.exe /setup, you should take care not to repeat a key binding.