Walkthrough: Displaying Statement Completion
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at Walkthrough: Displaying Statement Completion.
You can implement language-based statement completion by defining the identifiers for which you want to provide completion and then triggering a completion session. You can define statement completion in the context of a language service, define your own file name extension and content type and then display completion for just that type, or you can trigger completion for an existing content type—for example, "plaintext". This walkthrough shows how to trigger statement completion for the "plaintext" content type, which is the content type of text files. The "text" content type is the ancestor of all other content types, including code and XML files.
Statement completion is typically triggered by typing certain characters—for example, by typing the beginning of an identifier such as "using". It is typically dismissed by pressing the Spacebar, Tab, or Enter key to commit a selection. You can implement the IntelliSense features that are triggered by typing a character by using a command handler for the keystrokes (the IOleCommandTarget interface) and a handler provider that implements the IVsTextViewCreationListener interface. To create the completion source, which is the list of identifiers that participate in completion, implement the ICompletionSource interface and a completion source provider (the ICompletionSourceProvider interface). The providers are Managed Extensibility Framework (MEF) component parts. They are responsible for exporting the source and controller classes and importing services and brokers—for example, the ITextStructureNavigatorSelectorService, which enables navigation in the text buffer, and the ICompletionBroker, which triggers the completion session.
This walkthrough shows how to implement statement completion for a hard-coded set of identifiers. In full implementations, the language service and the language documentation are responsible for providing that content.
Starting in Visual Studio 2015, you do not install the Visual Studio SDK from the download center. It is included as an optional feature in Visual Studio setup. You can also install the VS SDK later on. For more information, see Installing the Visual Studio SDK.
To create a MEF project
Create a C# VSIX project. (In the New Project dialog, select Visual C# / Extensibility, then VSIX Project.) Name the solution
CompletionTest.Add an Editor Classifier item template to the project. For more information, see Creating an Extension with an Editor Item Template.
Delete the existing class files.
Add the following references to the project and make sure that CopyLocal is set to
false:Microsoft.VisualStudio.Editor
Microsoft.VisualStudio.Language.Intellisense
Microsoft.VisualStudio.OLE.Interop
Microsoft.VisualStudio.Shell.14.0
Microsoft.VisualStudio.Shell.Immutable.10.0
Microsoft.VisualStudio.TextManager.Interop
The completion source is responsible for collecting the set of identifiers and adding the content to the completion window when a user types a completion trigger, such as the first letters of an identifier. In this example, the identifiers and their descriptions are hard-coded in the AugmentCompletionSession method. In most real-world uses, you would use your language’s parser to get the tokens to populate the completion list.
To implement the completion source
Add a class file and name it
TestCompletionSource.Add these imports:
Imports System Imports System.Collections.Generic Imports System.Linq Imports System.Text Imports System.ComponentModel.Composition Imports Microsoft.VisualStudio.Language.Intellisense Imports Microsoft.VisualStudio.Text Imports Microsoft.VisualStudio.Text.Operations Imports Microsoft.VisualStudio.Utilities
Modify the class declaration for
TestCompletionSourceso that it implements ICompletionSource:Add private fields for the source provider, the text buffer, and a list of Completion objects (which correspond to the identifiers that will participate in the completion session):
Add a constructor that sets the source provider and buffer. The
TestCompletionSourceProviderclass is defined in later steps:Implement the AugmentCompletionSession method by adding a completion set that contains the completions you want to provide in the context. Each completion set contains a set of Completion completions, and corresponds to a tab of the completion window. (In Visual Basic projects, the completion window tabs are named Common and All.) The FindTokenSpanAtPosition method is defined in the next step.
Private Sub AugmentCompletionSession(ByVal session As ICompletionSession, ByVal completionSets As IList(Of CompletionSet)) Implements ICompletionSource.AugmentCompletionSession Dim strList As New List(Of String)() strList.Add("addition") strList.Add("adaptation") strList.Add("subtraction") strList.Add("summation") m_compList = New List(Of Completion)() For Each str As String In strList m_compList.Add(New Completion(str, str, str, Nothing, Nothing)) Next str completionSets.Add(New CompletionSet( "Tokens", "Tokens", FindTokenSpanAtPosition(session.GetTriggerPoint(m_textBuffer), session), m_compList, Nothing)) End SubThe following method is used to find the current word from the position of the cursor:
Private Function FindTokenSpanAtPosition(ByVal point As ITrackingPoint, ByVal session As ICompletionSession) As ITrackingSpan Dim currentPoint As SnapshotPoint = (session.TextView.Caret.Position.BufferPosition) - 1 Dim navigator As ITextStructureNavigator = m_sourceProvider.NavigatorService.GetTextStructureNavigator(m_textBuffer) Dim extent As TextExtent = navigator.GetExtentOfWord(currentPoint) Return currentPoint.Snapshot.CreateTrackingSpan(extent.Span, SpanTrackingMode.EdgeInclusive) End FunctionImplement the
Dispose()method:
The completion source provider is the MEF component part that instantiates the completion source.
To implement the completion source provider
Add a class named
TestCompletionSourceProviderthat implements ICompletionSourceProvider. Export this class with a ContentTypeAttribute of "plaintext" and a NameAttribute of "test completion".Import a ITextStructureNavigatorSelectorService, which is used to find the current word in the completion source.
Implement the TryCreateCompletionSource method to instantiate the completion source.
The completion command handler provider is derived from a IVsTextViewCreationListener, which listens for a text view creation event and converts the view from an IVsTextView—which enables the addition of the command to the command chain of the Visual Studio shell—to an ITextView. Because this class is a MEF export, you can also use it to import the services that are required by the command handler itself.
To implement the completion command handler provider
Add a file named
TestCompletionCommandHandler.Add these using statements:
Imports System Imports System.Collections.Generic Imports System.Linq Imports System.Text Imports System.ComponentModel.Composition Imports System.Runtime.InteropServices Imports Microsoft.VisualStudio Imports Microsoft.VisualStudio.Editor Imports Microsoft.VisualStudio.Language.Intellisense Imports Microsoft.VisualStudio.OLE.Interop Imports Microsoft.VisualStudio.Shell Imports Microsoft.VisualStudio.Text Imports Microsoft.VisualStudio.Text.Editor Imports Microsoft.VisualStudio.TextManager.Interop Imports Microsoft.VisualStudio.Utilities
Add a class named
TestCompletionHandlerProviderthat implements IVsTextViewCreationListener. Export this class with a NameAttribute of "token completion handler", a ContentTypeAttribute of "plaintext", and a TextViewRoleAttribute of Editable.Import the IVsEditorAdaptersFactoryService, which enables conversion from a IVsTextView to a ITextView, a ICompletionBroker, and a SVsServiceProvider that enables access to standard Visual Studio services.
Implement the VsTextViewCreated method to instantiate the command handler.
Public Sub VsTextViewCreated(ByVal textViewAdapter As IVsTextView) Implements IVsTextViewCreationListener.VsTextViewCreated Dim textView As ITextView = AdapterService.GetWpfTextView(textViewAdapter) If textView Is Nothing Then Return End If Dim createCommandHandler As Func(Of TestCompletionCommandHandler) = Function() New TestCompletionCommandHandler(textViewAdapter, textView, Me) textView.Properties.GetOrCreateSingletonProperty(createCommandHandler) End Sub
Because statement completion is triggered by keystrokes, you must implement the IOleCommandTarget interface to receive and process the keystrokes that trigger, commit, and dismiss the completion session.
To implement the completion command handler
Add a class named
TestCompletionCommandHandlerthat implements IOleCommandTarget:Add private fields for the next command handler (to which you pass the command), the text view, the command handler provider (which enables access to various services), and a completion session:
Add a constructor that sets the text view and the provider fields, and adds the command to the command chain:
Implement the QueryStatus method by passing the command along:
Implement the Exec method. When this method receives a keystroke, it must do one of these things:
Allow the character to be written to the buffer, and then trigger or filter completion. (Printing characters do this.)
Commit the completion, but do not allow the character to be written to the buffer. (Whitespace, Tab, and Enter do this when a completion session is displayed.)
Allow the command to be passed on to the next handler. (All other commands.)
Because this method may display UI, call IsInAutomationFunction to make sure that it is not called in an automation context:
Public 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 VsShellUtilities.IsInAutomationFunction(m_provider.ServiceProvider) Then Return m_nextCommandHandler.Exec(pguidCmdGroup, nCmdID, nCmdexecopt, pvaIn, pvaOut) End If 'make a copy of this so we can look at it after forwarding some commands Dim commandID As UInteger = nCmdID Dim typedChar As Char = Char.MinValue 'make sure the input is a char before getting it If pguidCmdGroup = VSConstants.VSStd2K AndAlso nCmdID = CUInt(VSConstants.VSStd2KCmdID.TYPECHAR) Then typedChar = CChar(ChrW(CUShort(Marshal.GetObjectForNativeVariant(pvaIn)))) End If 'check for a commit character If nCmdID = CUInt(VSConstants.VSStd2KCmdID.RETURN) OrElse nCmdID = CUInt(VSConstants.VSStd2KCmdID.TAB) OrElse (Char.IsWhiteSpace(typedChar) OrElse Char.IsPunctuation(typedChar)) Then 'check for a a selection If m_session IsNot Nothing AndAlso (Not m_session.IsDismissed) Then 'if the selection is fully selected, commit the current session If m_session.SelectedCompletionSet.SelectionStatus.IsSelected Then m_session.Commit() 'also, don't add the character to the buffer Return VSConstants.S_OK Else 'if there is no selection, dismiss the session m_session.Dismiss() End If End If End If 'pass along the command so the char is added to the buffer Dim retVal As Integer = m_nextCommandHandler.Exec(pguidCmdGroup, nCmdID, nCmdexecopt, pvaIn, pvaOut) Dim handled As Boolean = False If (Not typedChar.Equals(Char.MinValue)) AndAlso Char.IsLetterOrDigit(typedChar) Then If m_session Is Nothing OrElse m_session.IsDismissed Then ' If there is no active session, bring up completion Me.TriggerCompletion() m_session.Filter() Else 'the completion session is already active, so just filter m_session.Filter() End If handled = True ElseIf commandID = CUInt(VSConstants.VSStd2KCmdID.BACKSPACE) OrElse commandID = CUInt(VSConstants.VSStd2KCmdID.DELETE) Then 'redo the filter if there is a deletion If m_session IsNot Nothing AndAlso (Not m_session.IsDismissed) Then m_session.Filter() End If handled = True End If If handled Then Return VSConstants.S_OK End If Return retVal End FunctionThis code is a private method that triggers the completion session:
Private Function TriggerCompletion() As Boolean 'the caret must be in a non-projection location Dim caretPoint As SnapshotPoint? = m_textView.Caret.Position.Point.GetPoint(Function(textBuffer) ((Not textBuffer.ContentType.IsOfType("projection"))), PositionAffinity.Predecessor) If Not caretPoint.HasValue Then Return False End If m_session = m_provider.CompletionBroker.CreateCompletionSession(m_textView, caretPoint.Value.Snapshot.CreateTrackingPoint(caretPoint.Value.Position, PointTrackingMode.Positive), True) 'subscribe to the Dismissed event on the session AddHandler m_session.Dismissed, AddressOf OnSessionDismissed m_session.Start() Return True End FunctionThe next example is a private method that unsubscribes from the Dismissed event:
To test this code, build the CompletionTest solution and run it in the experimental instance.
To build and test the CompletionTest solution
Build the solution.
When you run this project in the debugger, a second instance of Visual Studio is instantiated.
Create a text file and type some text that includes the word "add".
As you type first "a" and then "d", a list that contains "addition" and "adaptation" should be displayed. Notice that addition is selected. When you type another "d", the list should contain only "addition", which is now selected. You can commit "addition" by pressing the Spacebar, Tab, or Enter key, or dismiss the list by typing Esc or any other key.
Walkthrough: Linking a Content Type to a File Name Extension