Walkthrough: Displaying Signature Help
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 Signature Help.
Signature Help (also known as Parameter Info) displays the signature of a method in a tooltip when a user types the parameter list start character (typically an opening parenthesis). As a parameter and parameter separator (typically a comma) are typed, the tooltip is updated to show the next parameter in bold. You can define Signature Help in the context of a language service, or you can define your own file name extension and content type and display Signature Help for just that type, or you can display Signature Help for an existing content type (for example, "text"). This walkthrough shows how to display Signature Help for the "text" content type.
Signature Help is typically triggered by typing a specific character, for example, "(" (opening parenthesis), and dismissed by typing another character, for example, ")" (closing parenthesis). IntelliSense features that are triggered by typing a character can be implemented by using a command handler for the keystrokes (the IOleCommandTarget interface) and a handler provider that implements the IVsTextViewCreationListener interface. To create the Signature Help source, which is the list of signatures that participate in Signature Help, implement the ISignatureHelpSource interface and a source provider that implements the ISignatureHelpSourceProvider interface. The providers are Managed Extensibility Framework (MEF) component parts, and are responsible for exporting the source and controller classes and importing services and brokers, for example, the ITextStructureNavigatorSelectorService, which lets you navigate in the text buffer, and the ISignatureHelpBroker, which triggers the Signature Help session.
This walkthrough shows how to implement Signature Help for a hard-coded set of identifiers. In full implementations, the language is 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
SignatureHelpTest.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 CopyLocal is set to
false:Microsoft.VisualStudio.Editor
Microsoft.VisualStudio.Language.Intellisense
Microsoft.VisualStudio.OLE.Interop
Microsoft.VisualStudio.Shell.14.0
Microsoft.VisualStudio.TextManager.Interop
The Signature Help source is based on signatures that implement ISignature, each of which contains parameters that implement IParameter. In a full implementation, this information would be obtained from the language documentation, but in this example, the signatures are hard-coded.
To implement the Signature Help signatures and parameters
Add a class file and name it
SignatureHelpSource.Add the following imports.
Add a class named
TestParameterthat implements IParameter.Add a constructor that sets all the properties.
Add the properties of IParameter.
Add a class named
TestSignaturethat implements ISignature.Add some private fields.
Add a constructor that sets the fields and subscribes to the Changed event.
Declare a
CurrentParameterChangedevent. This event is raised when the user fills in one of the parameters in the signature.Implement the CurrentParameter property so that it raises the
CurrentParameterChangedevent when the property value is changed.Add a method that raises the
CurrentParameterChangedevent.Add a method that computes the current parameter by comparing the number of commas in the ApplicableToSpan to the number of commas in the signature.
Add an event handler for the Changed event that calls the
ComputeCurrentParameter()method.Implement the ApplicableToSpan property. This property holds an ITrackingSpan that corresponds to the span of text in the buffer to which the signature applies.
Implement the other parameters.
The Signature Help source is the set of signatures for which you provide information.
To implement the Signature Help source
Add a class named
TestSignatureHelpSourcethat implements ISignatureHelpSource.Add a reference to the text buffer.
Add a constructor that sets the text buffer and the Signature Help source provider.
Implement the AugmentSignatureHelpSession method. In this example, the signatures are hard-coded, but in a full implementation you would get this information from the language documentation.
The helper method
CreateSignature()is provided just for illustration.Implement the GetBestMatch method. In this example, there are just two signatures, each of which has two parameters. Therefore, this method is not required. In a fuller implementation, in which more than one Signature Help source is available, this method is used to decide whether the highest-priority Signature Help source can supply a matching signature. If it cannot, the method returns null and the next-highest-priority source is asked to supply a match.
Implement the Dispose() method:
The Signature Help source provider is responsible for exporting the Managed Extensibility Framework (MEF) component part and for instantiating the Signature Help source.
To implement the Signature Help source provider
Add a class named
TestSignatureHelpSourceProviderthat implements ISignatureHelpSourceProvider, and export it with a NameAttribute, a ContentTypeAttribute of "text", and an OrderAttribute of Before="default".Implement TryCreateSignatureHelpSource by instantiating the
TestSignatureHelpSource.
Signature Help is typically triggered by a ( character and dismissed by a ) character. You can handle these keystrokes by implementing a IOleCommandTarget so that it triggers a Signature Help session when it receives a ( character preceded by a known method name, and dismisses the session when it receives a ) character.
To implement the command handler
Add a class named
TestSignatureHelpCommandthat implements IOleCommandTarget.Add private fields for the IVsTextView adapter (which lets you add the command handler to the chain of command handlers), the text view, the Signature Help broker and session, a ITextStructureNavigator, and the next IOleCommandTarget.
Add a constructor to initialize these fields and to add the command filter to the chain of command filters.
Implement the Exec method to trigger the Signature Help session when the command filter receives a ( character after one of the known method names, and to dismiss the session when it receives a ) character while the session is still active. In every case, the command is forwarded.
Implement the QueryStatus method so that it always forwards the command.
You can provide the Signature Help command by implementing the IVsTextViewCreationListener to instantiate the command handler when the text view is created.
To implement the Signature Help command provider
Add a class named
TestSignatureHelpControllerthat implements IVsTextViewCreationListener and export it with the NameAttribute, ContentTypeAttribute, and TextViewRoleAttribute.Import the IVsEditorAdaptersFactoryService (used to get the ITextView, given the IVsTextView object), the ITextStructureNavigatorSelectorService (used to find the current word), and the ISignatureHelpBroker (to trigger the Signature Help session).
Implement the VsTextViewCreated method by instantiating the
TestSignatureCommandHandler.
To test this code, build the SignatureHelpTest solution and run it in the experimental instance.
To build and test the SignatureHelpTest 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" plus an opening parenthesis.
After you type the opening parenthesis, you should see a tooltip that displays a list of the two signatures for the
add()method.
Walkthrough: Linking a Content Type to a File Name Extension