Parameter Info in a legacy language service 2

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

IntelliSense Parameter Info is a tooltip that displays the signature of a method when the user types the parameter list start character (typically an open parenthesis) for the method parameter list. As each parameter is entered and the parameter separator (typically a comma) is typed, the tooltip is updated to show the next parameter in bold.

The managed package framework (MPF) classes provide support for managing the Parameter Info tooltip. The parser must detect parameter start, parameter next, and parameter end characters, and it must supply a list of the method signatures and their associated parameters.

Legacy language services are implemented as part of a VSPackage, but the newer way to implement language service features is to use MEF extensions. To find out more, see Extending the Editor and Language Services.

Note

We recommend that you begin to use the new editor API as soon as possible. This will improve the performance of your language service and let you take advantage of new editor features.

Implementation

The parser should set the trigger value TokenTriggers is set when it finds a parameter list start character (often an open parenthesis). It should set a TokenTriggers trigger when it finds a parameter separator (often a comma). This causes a Parameter Info tooltip to be updated and show the next parameter in bold. The parser should set the trigger value TokenTriggers when if finds the parameter list end character (often a close parenthesis).

The TokenTriggers trigger value initiates a call to the MethodTip method, which in turn calls the ParseSource method parser with a parse reason of ParseReason. If the parser determines that the identifier before the parameter list start character is a recognized method name, it returns a list of matching method signatures in the AuthoringScope object. If any method signatures were found, the Parameter Info tooltip is displayed with the first signature in the list. This tooltip is then updated as more of the signature is typed. When the parameter list end character is typed, the Parameter Info tooltip is removed from view.

Note

To ensure that the Parameter Info tooltip is properly formatted, you must override the properties on the Methods class to supply the appropriate characters. The base Methods class assumes a C#-style method signature. See the Methods class for details on how this can be done.

Enabling Support for the Parameter Info

To support Parameter Info tooltips, you must set the ShowCompletion named parameter of the ProvideLanguageServiceAttribute to true. The language service reads the value of this registry entry from the EnableCodeSense property.

In addition, the ParameterInformation property must be set to true for the Parameter Info tooltip to be shown.

Example

Here is a simplified example of detecting the parameter list characters and setting the appropriate triggers. This example is for illustrative purposes only. It assumes that your scanner contains a method GetNextToken that identifies and returns tokens from a line of text. The example code simply sets the triggers whenever it sees the right kind of character.

using Microsoft.VisualStudio.Package;
using Microsoft.VisualStudio.TextManager.Interop;

namespace TestLanguagePackage
{
    public class TestScanner : IScanner
    {
        private Lexer lex;
        private const char parameterListStartChar = '(';
        private const char parameterListEndChar   = ')';
        private const char parameterNextChar      = ',';

        public bool ScanTokenAndProvideInfoAboutIt(TokenInfo tokenInfo,
                                                   ref int state)
        {
            bool foundToken = false
            string token = lex.GetNextToken();
            if (token != null)
            {
                foundToken = true;
                char c = token[0];
                if (Char.IsPunctuation(c))
                {
                    tokenInfo.Type = TokenType.Operator;
                    tokenInfo.Color = TokenColor.Keyword;
                    tokenInfo.EndIndex = index;

                    if (c == parameterListStartChar)
                    {
                        tokenInfo.Trigger |= TokenTriggers.ParameterStart;
                    }
                    else if (c == parameterListNextChar)
                    {
                        tokenInfo.Trigger |= TokenTriggers.ParameterNext;
                    else if (c == parameterListEndChar)
                    {
                        tokenInfo.Trigger |= TokenTriggers.ParameterEnd;
                    }
                }
            return foundToken;
        }
    }
}

Supporting the Parameter Info ToolTip in the Parser

The Source class makes some assumptions about the contents of the AuthoringScope and AuthoringSink classes when the Parameter Info tooltip is displayed and updated.

  • The parser is given ParseReason when the parameter list start character is typed.

  • The location given in the ParseRequest object is immediately after the parameter list start character. The parser must collect the signatures of all method declarations available at that position and store them in a list in your version of the AuthoringScope object. This list includes the method name, method type (or return type), and a list of possible parameters. This list is later searched for the method signature or signatures to display in the Parameter Info tooltip.

    The parser must then parse the line specified by the ParseRequest object to gather the name of the method being entered as well as how far along the user is in typing parameters. This is accomplished by passing the name of the method to the StartName method on the AuthoringSink object and then calling the StartParameters method when the parameter list start character is parsed, calling the NextParameter method when the parameter list next character is parsed, and finally calling the EndParameters method when the parameter list end character is parsed. The results of these method calls are used by the Source class to update the Parameter Info tooltip appropriately.

Example

Here is a line of text the user might enter. The numbers below the line indicate which step is taken by the parser at that position in the line (assuming parsing moves left to right). The assumption here is that everything before the line has already been parsed for method signatures, including the "testfunc" method signature.

testfunc("a string",3);
     ^^          ^ ^
     12          3 4

The steps that the parser takes are outlined below:

  1. The parser calls StartName with the text "testfunc".

  2. The parser calls StartParameters.

  3. The parser calls NextParameter.

  4. The parser calls EndParameters.