How to: Provide Expanded Outlining Support in a Legacy Language Service

There are two options for extending outlining support for your language beyond supporting the Collapse to Definitions command. You can add editor-controlled outline regions and add client-controlled outline regions.

Adding Editor-controlled Outline Regions

Use this approach to create an outline region and then allow the editor to handle whether the region is expanded, collapsed, and so forth. Of the two options for providing outlining support, this option is the least robust. For this option, you create a new outline region over a specified span of text using AddOutlineRegions. After this region is created, its behavior is controlled by the editor. Use the following procedure to implement editor-controlled outline regions.

To implement an editor-controlled outline region

1. Call QueryService for SVsTextManager

   This returns a pointer to IVsHiddenTextManager.

2. Call GetHiddenTextSession, passing in a pointer for a given text buffer. This returns a pointer to the IVsHiddenTextSession object for the buffer.

3. Call QueryInterface on IVsHiddenTextSession for a pointer to IVsOutliningSession.

4. Call AddOutlineRegions to add one or more new outline regions at a time.

   This method allows you to specify the span of text to outline, whether existing outline regions are removed or preserved, and whether the outline region is expanded or collapsed by default.

Adding Client-controlled Outline Regions

Use this approach to implement client-controlled (or smart) outlining like that used by the Visual C# and Visual Basic language services. A language service that manages its own outlining monitors the text buffer contents in order to destroy old outline regions when they becomes invalid and to create new outline regions as needed.

To implement a client-controlled outline region

1. Call QueryService for SVsTextManager. This returns a pointer to IVsHiddenTextManager.

2. Call GetHiddenTextSession, passing in a pointer for a given text buffer. This determines whether a hidden text session already exists for the buffer.

3. If a text session already exists, then you do not need to create one, and a pointer to the existing IVsHiddenTextSession object is returned. Use this pointer to enumerate and create outline regions. Otherwise, call CreateHiddenTextSession to create a hidden text session for the buffer. A pointer to the IVsHiddenTextSession object is returned.

   Note

   When you call CreateHiddenTextSession, you can specify a hidden text client (that is, an IVsHiddenTextClient object). This client notifies you when a hidden text or outline region is expanded or collapsed by the user.

4. Call AddHiddenRegions structure) parameter: Specify a value of HIDDEN_REGION_TYPE in the iType member of the NewHiddenRegion structure to indicate that you are creating an outline region, rather than a hidden region. Specify whether the region is client-controlled or editor-controlled in the dwBehavior member of the NewHiddenRegion structure. Your smart outlining implementation can contain a mix of editor- and client-controlled outline regions. Specify the banner text that is displayed when your outline region is collapsed, such as "...", in the pszBanner member of the NewHiddenRegion structure. The editor's default banner text for a hidden region is "...".