Walkthrough: Adding a Keyboard Binding to an Editor Command

This walkthrough demonstrates how to programmatically bind a keyboard shortcut to a command on the Edit menu. It builds on the code created in Walkthrough: Adding a Command to an Editor Generated by the Package Wizard.

Prerequisites

To run and build this walkthrough, you must first build the sample code in Walkthrough: Adding a Command to an Editor Generated by the Package Wizard. You also must have Visual Studio 2008 and the Visual Studio SDK installed on your system.

Adding a Keyboard Shortcut

To bind a keyboard shortcut to an Edit menu command

1. Either follow the steps in Walkthrough: Adding a Command to an Editor Generated by the Package Wizard and then continue with the steps below, or open the TestEditor.sln solution file that you previously created.

2. Add a guidTestEditorCmdUI in Guids.cs to be passed as the pguidCmdUI parameter in the call to the CreateEditorInstance method.

   This is done because the editor generated by the Visual Studio Integration Package Wizard is an embedded editor, and the CreateEditorInstance method in EditorFactory.cs does not have a specific GUID supplied in the pguidCmdUI parameter. To correctly define the keyboard binding availability, in Guids.cs after the line public static readonly Guid guidTestEditorCmdSet = new Guid("{yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy}"); statement, add the following:

   //new pguidCmdUI GUID
   public static readonly Guid guidTestEditorCmdUI = new Guid("{aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa}");
   

   The GUIDs above are represented by letters rather than the actual GUIDs you generated in the TestEditor.sln file because each VSPackage has a unique GUID. Include the actual GUID for guidTestEditorCmdSet in your TestEditor Guid.cs file.

3. Generate a new guidTestEditorCmdSet GUID, represented as {aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa} in step 2. To do this, choose Create GUID on the Tools menu, and then replace the string of a's with the new GUID.

4. Add the following lines to Guids.h, after the line #define guidTestEditorCmdSet { 0xyyyyyyyy, 0xyyyy, 0xyyyy, { 0xyy, 0xyy, 0xyy, 0xyy, 0xyy, 0xyy, 0xyy, 0xyy} } and before the line #endif // _CTC_GUIDS_:

   //The guidTestEditorCmdSet
   #define guidTestEditorCmdUI{ 0xaaaaaaaa, 0xaaaa, 0xaaaa, { 0xaa, 0xaa, 0xaa, 0xaa, 0xaa, 0xaa, 0xaa, 0xaa } }
   

   As in the previous steps, the letter strings must be replaced by actual GUIDs in your VSPackage, as generated in step 3.

5. Replace the line pguidCmdUI = new Guid (); with the following:

     public int CreateEditorInstance(
       uint grfCreateDoc,
       string pszMkDocument,
       string pszPhysicalView,
       IVsHierarchy pvHier,
       uint itemid,
       System.IntPtr punkDocDataExisting,
       out System.IntPtr ppunkDocView,
       out System.IntPtr ppunkDocData,
       out string pbstrEditorCaption,
       out Guid pguidCmdUI,
       out int pgrfCDW)
      {
   Trace.WriteLine(string.Format(CultureInfo.CurrentCulture, "Entering {0} CreateEditorInstance()", this.ToString()));
      // Initialize to null
        ppunkDocView = new System.IntPtr ();
        ppunkDocData = new System.IntPtr ();
        //Assign guidTestEditorCmdUI to pguidCmdUI 
         pguidCmdUI = Vsip.TestEditor.GuidList.guidTestEditorCmdUI; 
         pgrfCDW = 0;
         pbstrEditorCaption = null;
   

   This passes the pguidCmdUI parameter to the CreateEditorInstance method in EditorFactory.cs.

6. In Solution Explorer, expand the TestEditorUI project, and then expand the Resource Files node. Right-click TestEditorUI.rc and click View Code on the drop-down menu. In the TestEditorUI.rc file add the following IDS_KEYBOARD resource string:

   // String Table
   //
   
   STRINGTABLE 
   BEGIN
       IDS_OFFICIALNAME        "Package Name"
       IDS_PRODUCTDETAILS      "Information about my package"
       IDS_COMPANYNAME         "Company"
       IDS_VERSION             "1.0"
       IDS_MINVSEDITION        "Standard"
       IDS_EDITOR_NAME         "My Test Editor"
       IDS_DEFAULT_NAME        "MytestExtFile.mytestext"
       IDS_EDITOR_TEMPLATE     "My Test Editor"
       IDS_FILE_DESCRIPTION    "My Test Editor File (mytestext)"
       IDS_READONLY            " [Read Only]"
       IDS_FORMATSTR           "Package Name files (*.mytestext)\n*. mytestext \n\n"
       IDS_OUTSIDEEDITORFILECHANGE    "This file has changed outside the editor. Do you wish to reload it?"
       IDS_KEYBOARD            "TestEditor"
   END
   

7. In Resource.h, add the following definition to define the IDS_KEYBOARD string resource:

   #define IDS_EDITOR_NAME               106
   #define IDS_DEFAULT_NAME              107
   #define IDS_EDITOR_TEMPLATE           108
   #define IDS_FILE_DESCRIPTION          109
   #define IDS_READONLY                  110
   #define IDS_FORMATSTR                 111
   #define IDS_OUTSIDEEDITORFILECHANGE   112
   // Define the keyboard string resource 
   #define IDS_KEYBOARD                  121 
   

8. In VsPkg.cs add the registration attribute for the keyboard binding by adding the following line after [MSVSIP.ProvideMenuResource(1000, 1)]:

    [MSVSIP.ProvideKeyBindingTable("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", 121)] 
   

   The GUID passed to ProvideKeyBindingTableAttribute is the one you defined earlier for guidTestEditorCmdUI. The string resource IDS_KEYBOARD defines the registry entry that displays the name of your editor in the Keyboard options on the Tools menu.

9. To associate the keyboard binding of CTRL+SHIFT+ALT+G with the Color Text command on the Edit menu, add the following line to the KEYBINDINGS_SECTION of PkgCmd.ctc file:

   KEYBINDINGS_SECTION
   // 
   // This sections defines the keystroke mappings for the commands.
   // The Keystate field is done using the following:
   //    A = Alt, S = Shift, C = Control, W = Windows Key
   // Example of the Keystate assignment, if you want a two-key combination
   // of Ctrl-X, Ctrl-Shift-C then the syntax would be :
   //
   //    'x':C:'c':CS
   
   KEYBINDINGS_SECTION
   // Command   when available   emulation   keystate
   guidTestEditorCmdSet:cmdidColorFont, guidTestEditorCmdUI, guidTestEditorCmdUI, 'G':CSA; 
   KEYBINDINGS_END
   

   The guidTestEditorCmdSet:cmdidColorFont defines the command for which the keyboard binding applies, and guidTestEditorCmdUI defines the availability and emulation of the keyboard binding.

10. Build your solution to verify that it builds and compiles without errors.

Testing Your Keyboard Binding

Code generated by the Visual Studio Integration Package Wizard includes a Devenv /rootsuffix exp command as a post-build event to merge the commands and UI elements of all the VSPackages in the experimental version of Visual Studio 2008.

To start an instance of Visual Studio Exp

• At the Visual Studio command prompt, type Devenv /rootsuffix exp.

To test your keyboard binding

1. On the File menu of the Visual Studio Exp, click New and then File. In the New File dialog box, expand the My Test Editor node.

2. In the Templates pane, select the My Test Editor template.

3. Click Open.

4. Expand the Edit menu to see all of the Test Editor–related commands.

   Only the Select All command is enabled; the others are disabled.

5. Type some text in the editor pane and select some of it.

   The commands Copy, Paste, Cut, and Color Text should be enabled.

6. Press the CTRL+SHIFT+ALT+G keyboard combination to color the selected text crimson.

7. Verify that your editor name appears in the ToolsOptions dialog box by clicking Options on the Tools menu. In the left-hand pane of the Options dialog box, select Keyboard.

   TestEditor should appear on the Use new shortcut in drop-down menu.

See Also

Concepts

How to: Create VSPackages (C# and VB)

Handling Keyboard Bindings