AuthoringSink.MatchPair(TextSpan, TextSpan, Int32) Method

Definition

Namespace:

Microsoft.VisualStudio.Package

Assembly:

Microsoft.VisualStudio.Package.LanguageService.15.0.dll

Package:

Microsoft.VisualStudio.Package.LanguageService.15.0 v17.12.40392

Whenever a matching pair is parsed, e.g. '{' and '}', this method is called with the text span of both the left and right item. The information is used when a user types "ctrl-]" in VS to find a matching brace and when auto-highlight matching braces is enabled. A priority can also be given so that multiple overlapping pairs can be prioritized for brace matching. The matching pair with the highest priority (largest integer value) wins.

public:
 virtual void MatchPair(Microsoft::VisualStudio::TextManager::Interop::TextSpan span, Microsoft::VisualStudio::TextManager::Interop::TextSpan endContext, int priority);

public:
 virtual void MatchPair(Microsoft::VisualStudio::TextManager::Interop::TextSpan span, Microsoft::VisualStudio::TextManager::Interop::TextSpan endContext, int priority);

 virtual void MatchPair(Microsoft::VisualStudio::TextManager::Interop::TextSpan span, Microsoft::VisualStudio::TextManager::Interop::TextSpan endContext, int priority);

public virtual void MatchPair (Microsoft.VisualStudio.TextManager.Interop.TextSpan span, Microsoft.VisualStudio.TextManager.Interop.TextSpan endContext, int priority);

abstract member MatchPair : Microsoft.VisualStudio.TextManager.Interop.TextSpan * Microsoft.VisualStudio.TextManager.Interop.TextSpan * int -> unit
override this.MatchPair : Microsoft.VisualStudio.TextManager.Interop.TextSpan * Microsoft.VisualStudio.TextManager.Interop.TextSpan * int -> unit

Public Overridable Sub MatchPair (span As TextSpan, endContext As TextSpan, priority As Integer)

Parameters

span

TextSpan

[in] The TextSpan object describing the starting paired element.

endContext

TextSpan

[in] The TextSpan object describing the ending paired element.

priority

Int32

[in] A priority value used to sort overlapping pairs.

Examples

The following structure is used by the managed package framework to contain a prioritized pair of language elements (for example, "(" and ")").

internal class BraceMatch  
{  
    internal TextSpan a;  
    internal TextSpan b;  
    internal int priority;  

    public BraceMatch(TextSpan a, TextSpan b, int priority)  
    {  
        this.a = a;  
        this.b = b;  
        this.priority = priority;  
    }  
}  

Remarks

If the BraceMatching property returns true, this method is called to add the two spans to an internal list that describes matching pairs, sorted in priority order (typically the highest priority for overlapping pairs wins) that is used for overlapping pairs. Some examples of matching pairs are "(", ")"; "{", "}"; and "<", ">".

One way where matching pairs overlap is with nested braces. In this scheme, the innermost pair of braces has the highest priority and the outermost pair has the lowest priority.

The base method normalizes the spans and then determines if the spans include the parse operation's starting point (as given by the Line and Column properties). If either span includes the starting point, the spans are first added to an internal list of spans and are then bundled into a BraceMatch structure added to another internal list, sorted in priority order. The internal list is an array of BraceMatch structures and is called Braces. See the example below for the internal definition of the BraceMatch structure.