KEYBINDINGS_SECTION – KEYBINDINGS_END

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.

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.

  注意

  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:Accel
  

  In 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.

    注意

    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.

See Also

Concepts

How VSPackages Add User Interface Elements

CMDS_SECTION – CMDS_END