ExpansionProvider Class

  • Article

Provides support for inserting code snippets into source code.

This API is not CLS-compliant. 

Inheritance Hierarchy

System.Object
  Microsoft.VisualStudio.Package.ExpansionProvider

Namespace:  Microsoft.VisualStudio.Package
Assemblies:   Microsoft.VisualStudio.Package.LanguageService.10.0 (in Microsoft.VisualStudio.Package.LanguageService.10.0.dll)
  Microsoft.VisualStudio.Package.LanguageService (in Microsoft.VisualStudio.Package.LanguageService.dll)
  Microsoft.VisualStudio.Package.LanguageService.9.0 (in Microsoft.VisualStudio.Package.LanguageService.9.0.dll)
  Microsoft.VisualStudio.Package.LanguageService.11.0 (in Microsoft.VisualStudio.Package.LanguageService.11.0.dll)

Syntax

'Declaration
<CLSCompliantAttribute(False)> _
<ComVisibleAttribute(True)> _
Public Class ExpansionProvider _
    Implements IDisposable, IVsExpansionClient

[CLSCompliantAttribute(false)]
[ComVisibleAttribute(true)]
public class ExpansionProvider : IDisposable, 
    IVsExpansionClient

[CLSCompliantAttribute(false)]
[ComVisibleAttribute(true)]
public ref class ExpansionProvider : IDisposable, 
    IVsExpansionClient

[<CLSCompliantAttribute(false)>]
[<ComVisibleAttribute(true)>]
type ExpansionProvider =  
    class 
        interface IDisposable 
        interface IVsExpansionClient 
    end

public class ExpansionProvider implements IDisposable, IVsExpansionClient

The ExpansionProvider type exposes the following members.

Constructors

  Name Description
Public method ExpansionProvider Initializes a new instance of the ExpansionProvider class.

Top

Properties

  Name Description
Public property Expansion Returns the IVsExpansion object used for inserting snippets into a buffer.
Public property ExpansionSession Returns the expansion session created to manage editing the code snippet.
Public property InTemplateEditingMode Indicates whether the code snippet is currently being edited.
Public property Source Returns the Source object associated with this expansion provider.
Public property TextView Returns the text view containing the source file being manipulated by the expansion provider.

Top

Methods

  Name Description
Public method BeginTemplateEditing Inserts the previously prepared code snippet and starts the snippet editing mode.
Public method DisplayExpansionBrowser Displays a list of expansion templates of the specified type and kind.
Public method Dispose Cleans up allocated resource just before the ExpansionProvider object is destroyed.
Public method EndExpansion Called when an expansion session has ended.
Public method EndTemplateEditing Ends the current snippet editing mode.
Public method Equals Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected method Finalize Cleans up all resources just before the ExpansionProvider object is destroyed. (Overrides Object.Finalize().)
Public method FindExpansionByShortcut Obtains the path and title of a code snippet given the snippet's shortcut name.
Public method FormatSpan Formats the specified text span.
Public method GetExpansionFunction(XmlElement, String) Returns an IVsExpansionFunction object representing the expansion function described in the given XML template node.
Public method GetExpansionFunction(IXMLDOMNode, String, IVsExpansionFunction%) Returns a IVsExpansionFunction object representing the expansion function described in the given XML template node (COM implementation).
Public method GetExpansionSpan Returns the span occupied by the snippet currently being edited.
Public method GetFieldSpan Gets the field span of the specified field
Public method GetFieldValue Returns the value of the specified field.
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Public method HandlePostExec Called after a command has been executed.
Public method HandlePreExec Called before a command is executed.
Public method HandleQueryStatus Determines if the specified command is handled by the ExpansionProvider class.
Public method InsertNamedExpansion Inserts the specified snippet into the source at the given position.
Public method InsertSpecificExpansion Inserts the specific snippet into the source at the specified position.
Public method IsValidKind Determines whether this is valid text for expansion. This method should be overridden if you want to specify where in the source document the expansion can take place.
Public method IsValidType Determines whether or not a given type is valid for expansion purposes. This method should be overridden if you want to specify where in the source document the expansion can take place.
Protected method MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public method OnAfterInsertion Called after a snippet has been inserted into the source.
Public method OnBeforeInsertion Called just before the snippet has been inserted into the source.
Public method OnItemChosen Called when an item is chosen in a snippet browser.
Public method PositionCaretForEditing Puts the caret in a position suitable for editing.
Public method PrepareTemplate Prepares for insertion of the specified snippet.
Public method ToString Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

A code snippet is a template that is expanded into full code when the user inserts the snippet. When the snippet is first expanded, the Visual Studio core editor enters a special template editing mode where the snippet can be modified in place. That is, certain parts of the snippet are designated as fields, and these fields can easily be changed by the user before the snippet is committed to the editor's buffer. The fields are highlighted and can feature drop-down boxes offering choices to the user.

A snippet has a name to identify it and a template file containing the snippet itself. The template file contains XML tags indicating specific elements of the template, from the code to substitution fields to functions (known as expansion functions). See Code Snippets for more details on code snippets.

Notes to Implementers

The ExpansionProvider class provides all the support for selecting and inserting a code snippet into a source file. The base class provides all the basic functionality; however, if you want to support context-sensitive snippet insertion (that is, a snippet with the same name might behave differently depending on the context into which it is inserted), then you must derive a class from the ExpansionProvider class and override the IsValidType and IsValidKind methods to report the appropriate snippet type and kind that are allowed in a particular context. Be sure to override the CreateExpansionProvider method in your version of the LanguageService class to return your version of the ExpansionProvider class.

Notes to Callers

An instance of the ExpansionProvider class is returned from the CreateExpansionProvider method in the LanguageService class that is called from the GetExpansionProvider method in the Source class. The ViewFilter class calls its own GetExpansionProvider that in turn forwards the call to the GetExpansionProvider method in the Source class. The ViewFilter class calls the GetExpansionProvider method any time a command is executed to allow the ExpansionProvider class a chance to act.

Examples

Expansions are inserted in three ways:

  1. The code snippet browser,

  2. Selecting a snippet shortcut name from a completion list, or

  3. By typing a shortcut and entering a completion character such as a tab or space.

The following example shows one way to handle auto-expansion that is triggered by typing an expansion shortcut followed by the tab key. This method is called every time a tab key is typed.

using Microsoft.VisualStudio.Package;
using Microsoft.VisualStudio;

namespace MyLanguagePackage
{
    class MyViewFilter : ViewFilter
    {
        // This is called from our HandlePreExec when a tab key is pressed
        bool HandleTabKey()
        {
            ExpansionProvider ep = GetExpansionProvider();
            if (ep == null || ep.InTemplateEditingMode)
            {
                // No expansion provider or already editing a template,
                // so nothing to do.
                return false;
            }

            TokenInfo tokenInfo = Source.GetTokenInfo(TextView);
            if (tokenInfo.StartLine != tokenInfo.EndLine ||
                tokenInfo.StartIndex == tokenInfo.EndIndex)
            {
                // No shortcut found before caret, so nothing to do.
                // Note that the above test does not allow for single
                // character tokens to be shortcut names.
                return false;
            }

            int line;
            int col;
            int hr;
            hr = TextView.GetCaretPos(out line,out col);
            if (hr != VsConstants.S_OK)
            {
                // Could not get current position, so nothing to do.
                // GetCaretPos is used in Source.GetTokenInfo so if
                // GetCaretPos fails, GetTokenInfo fails. However,
                // better to be thorough and test again here.
                return false;
            }

            // Get shortcut text that was just typed.
            string shortcut = Source.GetText(line,
                                             tokenInfo.StartIndex,
                                             line,
                                             tokenInfo.EndIndex);
            if (shortcut == null || shortcut == "")
            {
                // No text was found at the position. This failure is
                // is not likely if GetTokenInfo returned a valid token
                // but better to be thorough.
                return false;
            }

            string snippetTitle;
            string snippetPath;
            TextSpan pos = new TextSpan();
            pos.iStartLine = line;
            pos.iStartIndex = tokenInfo.StartIndex;
            pos.iEndLine = line;
            pos.iEndIndex = tokenInfo.EndIndex;
            if (ep.FindExpansionByShortcut(TextView,
                                            shortcut,
                                            pos,
                                            true,
                                            out title,
                                            out path) != VSConstants.S_OK)
            {
                // No snippet matched the shortcut, so nothing to do.
                return false;
            }

            // If InsertNamedExpansion returns true, snippet was
            // inserted and therefore the Tab key was handled.
            // Otherwise, false is returned and the Tab key will be
            // passed on to someone else.
            return ep.InsertNamedExpansion(TextView,
                                           title,
                                           path,
                                           pos,
                                           false);
        }
    }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

Microsoft.VisualStudio.Package Namespace

Other Resources

Code Snippets

Code Snippets Schema Reference