| title | description | ms.date | ms.topic | helpviewer_keywords | author | ms.author | manager | ms.subservice | dev_langs | |||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Define and display outlining regions |
Define and display outlining regions in the context of a language service or for your own file name extension and content type in Visual Studio. |
11/04/2016 |
how-to |
|
maiak |
maiak |
mijacobs |
extensibility-integration |
|
Set up language-based features such as outlining by defining the kinds of text regions you want to expand or collapse. You can define regions in the context of a language service, or define your own file name extension and content type and apply the region definition to only that type, or apply the region definitions to an existing content type (such as "text"). This walkthrough shows how to define and display outlining regions.
-
Create a VSIX project. Name the solution
OutlineRegionTest. -
Add an Editor Classifier item template to the project. For more information, see Create an extension with an editor item template.
-
Delete the existing class files.
Outlining regions are marked by a kind of tag (xref:Microsoft.VisualStudio.Text.Tagging.OutliningRegionTag). This tag provides the standard outlining behavior. The outlined region can be expanded or collapsed. The outlined region is marked by a Plus sign (+) if it's collapsed or a Minus sign (-) if it's expanded, and the expanded region is demarcated by a vertical line.
The following steps show how to define a tagger that creates outlining regions for all the regions delimited by the brackets ([,]).
-
Add a class file and name it
OutliningTagger. -
Import the following namespaces.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet1":::
-
Create a class named
OutliningTagger, and have it implement xref:Microsoft.VisualStudio.Text.Tagging.ITagger%601::::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet2":::
-
Add some fields to track the text buffer and snapshot and to accumulate the sets of lines that should be tagged as outlining regions. This code includes a list of Region objects (to be defined later) that represent the outlining regions.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet3":::
-
Add a tagger constructor that initializes the fields, parses the buffer, and adds an event handler to the xref:Microsoft.VisualStudio.Text.ITextBuffer.Changed event.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet4":::
-
Implement the xref:Microsoft.VisualStudio.Text.Tagging.ITagger%601.GetTags%2A method, which instantiates the tag spans. This example assumes that the spans in the xref:Microsoft.VisualStudio.Text.NormalizedSpanCollection passed in to the method are contiguous, although it may not always be the case. This method instantiates a new tag span for each of the outlining regions.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet5":::
-
Declare a
TagsChangedevent handler.:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet6":::
-
Add a
BufferChangedevent handler that responds to xref:Microsoft.VisualStudio.Text.ITextBuffer.Changed events by parsing the text buffer.:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet7":::
-
Add a method that parses the buffer. The example given here is for illustration only. It synchronously parses the buffer into nested outlining regions.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet8":::
-
The following helper method gets an integer that represents the level of the outlining, such that 1 is the leftmost brace pair.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet9":::
-
The following helper method translates a Region (defined later in this article) into a SnapshotSpan.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet10":::
-
The following code is for illustration only. It defines a PartialRegion class that contains the line number and offset of the start of an outlining region, and a reference to the parent region (if any). This code enables the parser to set up nested outlining regions. A derived Region class contains a reference to the line number of the end of an outlining region.
:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet11":::
Export a tagger provider for your tagger. The tagger provider creates an OutliningTagger for a buffer of the "text" content type, or else returns an OutliningTagger if the buffer already has one.
-
Create a class named
OutliningTaggerProviderthat implements xref:Microsoft.VisualStudio.Text.Tagging.ITaggerProvider, and export it with the ContentType and TagType attributes.:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet12":::
-
Implement the xref:Microsoft.VisualStudio.Text.Tagging.ITaggerProvider.CreateTagger%2A method by adding an
OutliningTaggerto the properties of the buffer.:::code language="csharp" source="../snippets/csharp/VS_Snippets_VSSDK/vssdkoutlineregiontest/cs/outliningtagger.cs" id="Snippet13":::
To test this code, build the OutlineRegionTest solution and run it in the experimental instance.
-
Build the solution.
-
When you run this project in the debugger, a second instance of Visual Studio is started.
-
Create a text file. Type some text that includes both the opening brackets and the closing brackets.
[ Hello ] -
There should be an outlining region that includes both brackets. You should be able to click the Minus Sign to the left of the open bracket to collapse the outlining region. When the region is collapsed, the ellipsis symbol (...) should appear to the left of the collapsed region, and a popup containing the text hover text should appear when you move the pointer over the ellipsis.