Walkthrough: Using a Shortcut Key with an Editor Extension

Article
01/30/2013

You can respond to shortcut keys in your editor extension. The following walkthrough shows how to add a view adornment to a text view by using a shortcut key. This walkthrough is based on the viewport adornment editor template, and it allows you to add the adornment by using the + character.

Prerequisites

To complete this walkthrough, you must install the Visual Studio 2010 SDK.

Note

For more information about the Visual Studio SDK, see Visual Studio Integration SDK. To find out how to download the Visual Studio SDK, see Visual Studio Extensibility Developer Center on the MSDN Web site.

Creating a Managed Extensibility Framework (MEF) Project

To create a MEF project

Create an Editor Viewport Adornment project. Name the solution KeyBindingTest.
Open the source.extension.vsixmanifest file in the VSIX Manifest Editor.
Make sure that the Content heading contains a MEF Component content type and that the Path is set to KeyBindingTest.dll.
Save and close Source.extension.vsixmanifest.
Add the following references and set CopyLocal to false:

Microsoft.VisualStudio.Editor

Microsoft.VisualStudio.OLE.Interop

Microsoft.VisualStudio.Shell

Microsoft.VisualStudio.TextManager.Interop
Delete the KeyBindingTestFactory class file.

In the KeyBindingTest class file, change the class name to PurpleCornerBox. Change the constructor as well. Inside the constructor, change the line:

_adornmentLayer = view.GetAdornmentLayer("KeyBindingTest")

_adornmentLayer = view.GetAdornmentLayer("KeyBindingTest");

_adornmentLayer = view.GetAdornmentLayer("PurpleCornerBox")

_adornmentLayer = view.GetAdornmentLayer("PurpleCornerBox");

Defining the Command Filter

The command filter is an implementation of IOleCommandTarget, which handles the command by instantiating the adornment.

To define the command filter

Add a class file and name it KeyBindingCommandFilter.

Add the following using statements.

Imports System
Imports System.Runtime.InteropServices
Imports Microsoft.VisualStudio.OLE.Interop
Imports Microsoft.VisualStudio
Imports Microsoft.VisualStudio.Text.Editor

using System;
using System.Runtime.InteropServices;
using Microsoft.VisualStudio.OLE.Interop;
using Microsoft.VisualStudio;
using Microsoft.VisualStudio.Text.Editor;

The class named KeyBindingCommandFilter should inherit from IOleCommandTarget.

Friend Class KeyBindingCommandFilter
    Implements IOleCommandTarget

internal class KeyBindingCommandFilter : IOleCommandTarget

Add private fields for the text view, the next command in the command chain, and a flag to represent whether the command filter has already been added.

Private m_textView As IWpfTextView
Friend m_nextTarget As IOleCommandTarget
Friend m_added As Boolean
Friend m_adorned As Boolean

private IWpfTextView m_textView;
internal IOleCommandTarget m_nextTarget;
internal bool m_added;
internal bool m_adorned;

Add a constructor that sets the text view.

Public Sub New(ByVal textView As IWpfTextView)
    m_textView = textView
    m_adorned = False
End Sub

public KeyBindingCommandFilter(IWpfTextView textView)
{
    m_textView = textView;
    m_adorned = false;
}

Implement the QueryStatus() method as follows.

Private Function QueryStatus(ByRef pguidCmdGroup As Guid, ByVal cCmds As UInteger, ByVal prgCmds() As OLECMD, ByVal pCmdText As IntPtr) As Integer Implements IOleCommandTarget.QueryStatus
    Return m_nextTarget.QueryStatus(pguidCmdGroup, cCmds, prgCmds, pCmdText)
End Function

int IOleCommandTarget.QueryStatus(ref Guid pguidCmdGroup, uint cCmds, OLECMD[] prgCmds, IntPtr pCmdText)
{
    return m_nextTarget.QueryStatus(ref pguidCmdGroup, cCmds, prgCmds, pCmdText);
}

Implement the Exec() method so that it adds a purple box to the view if a + character is typed.

Private Function Exec(ByRef pguidCmdGroup As Guid, ByVal nCmdID As UInteger, ByVal nCmdexecopt As UInteger, ByVal pvaIn As IntPtr, ByVal pvaOut As IntPtr) As Integer Implements IOleCommandTarget.Exec
    If m_adorned = False Then
        Dim typedChar As Char = Char.MinValue

        If pguidCmdGroup = VSConstants.VSStd2K AndAlso nCmdID = CUInt(VSConstants.VSStd2KCmdID.TYPECHAR) Then
            typedChar = CChar(ChrW(Marshal.GetObjectForNativeVariant(pvaIn)))
            If typedChar.Equals("+"c) Then
                Dim TempPurpleCornerBox As PurpleCornerBox = New PurpleCornerBox(m_textView)
                m_adorned = True
            End If
        End If
    End If
    Return m_nextTarget.Exec(pguidCmdGroup, nCmdID, nCmdexecopt, pvaIn, pvaOut)
End Function

int IOleCommandTarget.Exec(ref Guid pguidCmdGroup, uint nCmdID, uint nCmdexecopt, IntPtr pvaIn, IntPtr pvaOut)
{
    if (m_adorned == false)
    {
        char typedChar = char.MinValue;

        if (pguidCmdGroup == VSConstants.VSStd2K && nCmdID == (uint)VSConstants.VSStd2KCmdID.TYPECHAR)
        {
            typedChar = (char)(ushort)Marshal.GetObjectForNativeVariant(pvaIn);
            if (typedChar.Equals('+'))
            {
                new PurpleCornerBox(m_textView);
                m_adorned = true;
            }
        }
    }
    return m_nextTarget.Exec(ref pguidCmdGroup, nCmdID, nCmdexecopt, pvaIn, pvaOut);
}

Adding the Command Filter Provider

The adornment provider must add a command filter to the text view. In this example, the provider implements IVsTextViewCreationListener to listen to text view creation events. This adornment provider also exports the adornment layer, which defines the Z-order of the adornment.

To add the command filter provider

Add a class file and name it KeyBindingFilterProvider.

Add the following using statements.

Imports System
Imports System.Collections.Generic
Imports System.ComponentModel.Composition
Imports Microsoft.VisualStudio
Imports Microsoft.VisualStudio.OLE.Interop
Imports Microsoft.VisualStudio.Utilities
Imports Microsoft.VisualStudio.Editor
Imports Microsoft.VisualStudio.Text.Editor
Imports Microsoft.VisualStudio.TextManager.Interop

using System;
using System.Collections.Generic;
using System.ComponentModel.Composition;
using Microsoft.VisualStudio;
using Microsoft.VisualStudio.OLE.Interop;
using Microsoft.VisualStudio.Utilities;
using Microsoft.VisualStudio.Editor;
using Microsoft.VisualStudio.Text.Editor;
using Microsoft.VisualStudio.TextManager.Interop;

Add a class named KeyBindingFilterProvider that inherits from IVsTextViewCreationListener, and export it with a content type of "text" and a TextViewRoleAttribute of Editable.

<Export(GetType(IVsTextViewCreationListener)), ContentType("text"), TextViewRole(PredefinedTextViewRoles.Editable)>
Friend Class KeyBindingCommandFilterProvider
    Implements IVsTextViewCreationListener

[Export(typeof(IVsTextViewCreationListener))]
[ContentType("text")]
[TextViewRole(PredefinedTextViewRoles.Editable)]
internal class KeyBindingCommandFilterProvider : IVsTextViewCreationListener

Add the adornment layer definition.

<Export(GetType(AdornmentLayerDefinition)), Name("PurpleCornerBox"), Order(), TextViewRole(PredefinedTextViewRoles.Editable)>
Friend keybindingAdornmentLayer As AdornmentLayerDefinition

[Export(typeof(AdornmentLayerDefinition))]
[Name("PurpleCornerBox")]
[Order()]
[TextViewRole(PredefinedTextViewRoles.Editable)]
internal AdornmentLayerDefinition keybindingAdornmentLayer;

To get the text view adapter, you must import the IVsEditorAdaptersFactoryService.

<Import(GetType(IVsEditorAdaptersFactoryService))>
Friend editorFactory As IVsEditorAdaptersFactoryService = Nothing

[Import(typeof(IVsEditorAdaptersFactoryService))]
internal IVsEditorAdaptersFactoryService editorFactory = null;

Implement the VsTextViewCreated method so that it adds the KeyBindingCommandFilter.

Public Sub VsTextViewCreated(ByVal textViewAdapter As IVsTextView) Implements IVsTextViewCreationListener.VsTextViewCreated
    Dim textView As IWpfTextView = editorFactory.GetWpfTextView(textViewAdapter)
    If textView Is Nothing Then
        Return
    End If

    AddCommandFilter(textViewAdapter, New KeyBindingCommandFilter(textView))
End Sub

public void VsTextViewCreated(IVsTextView textViewAdapter)
{
    IWpfTextView textView = editorFactory.GetWpfTextView(textViewAdapter);
    if (textView == null)
        return;

    AddCommandFilter(textViewAdapter, new KeyBindingCommandFilter(textView));
}

The AddCommandFilter handler gets the text view adapter and adds the command filter.

Private Sub AddCommandFilter(ByVal viewAdapter As IVsTextView, ByVal commandFilter As KeyBindingCommandFilter)
    If commandFilter.m_added = False Then
        'get the view adapter from the editor factory
        Dim [next] As IOleCommandTarget
        Dim hr As Integer = viewAdapter.AddCommandFilter(commandFilter, [next])

        If hr = VSConstants.S_OK Then
            commandFilter.m_added = True
            'you'll need the next target for Exec and QueryStatus
            If [next] IsNot Nothing Then
                commandFilter.m_nextTarget = [next]
            End If
        End If
    End If
End Sub

void AddCommandFilter(IVsTextView viewAdapter, KeyBindingCommandFilter commandFilter)
{
    if (commandFilter.m_added == false)
    {
        //get the view adapter from the editor factory
        IOleCommandTarget next;
        int hr = viewAdapter.AddCommandFilter(commandFilter, out next);

        if (hr == VSConstants.S_OK)
        {
            commandFilter.m_added = true;
            //you'll need the next target for Exec and QueryStatus
            if (next != null)
                commandFilter.m_nextTarget = next;
        }
    }
}

Building and Testing the Code

To test this code, build the KeyBindingTest solution and run it in the experimental instance.

To build and test the KeyBindingTest solution

Build the solution.
When you run this project in the debugger, a second instance of Visual Studio is instantiated.
Create or open a text file, and then click anywhere in the text view.
Type +.

Resize the text view.

A purple square should appear in the upper right corner of the text view.