Collapsing Regions Without Outlining

The code outlining feature described in earlier topics supports the collapsing of outlining nodes, where contained text becomes hidden. SyntaxEditor's low-level collapsed region management feature is harnessed to achieve this functionality. This same collapsed regions mechanism can be used independently of code outlining too.

Various text regions can be collapsed (hidden) independent of the outlining features. And in these cases, you can even optionally replace the collapsed region with an adornment.

Collapsed Region Manager

The ICollapsedRegionManager is the object that tracks all the collapsed regions for a particular view. A view's collapsed region manager is accessible via the ITextView.CollapsedRegionManager property.

When the view's text formatting engine builds up layout data for a view line, it consults the collapsed region manager to see if there are any collapsed regions that it needs to be aware of. When one is found, it ignores the contained text and moves onto the remaining text that should be rendered on the view line.

The ICollapsedRegionManager has two main functions:

• Raise an event when the collapsed regions change
• Allow consumers to return collapsed regions that contain an offset or intersect a text range

RegionsChanged Event

The manager watches all document text changes and also changes published by ICollapsedRegionTag taggers. When any of those changes occur, the manager updates its collapsed regions accordingly. If any regions are added or removed, the RegionsChanged event is raised, passing along the TextSnapshotRange that was changed.

Returning Intersecting Collapsed Regions

The ICollapsedRegionManager.GetCollapsedRange returns the TextSnapshotRange, if any, that contains the specified offset.

The GetCollapsedRanges method returns a NormalizedTextSnapshotRangeCollection of collapsed snapshot ranges that intersect the specified range, if any.

Tagging Collapsed Regions

The ICollapsedRegionTag is a dedicated tag type that the ICollapsedRegionManager watches for and uses to determine which regions are collapsed. SyntaxEditor's text formatting engine then consults the collapsed region manager and uses its data to determine when text should be rendered as collapsed (hidden).

Therefore to collapse a region of text without using code outlining, all you need to do is create a tagger for the ICollapsedRegionTag type and return appropriate tag ranges when requested. You can create a custom class that implements ICollapsedRegionTag and use that in your tagger results. The tagger can in installed by your language via a tagger provider service.

At this point if your tagger is in use by your language, you should notice hidden text wherever your tagger designates.

Rendering Intra-Text Adornments in Place of Collapsed Regions

Collapsed regions by default will not render anything in their place. However, there is an option to render an adornment in place of the collapsed region. The code outlining feature uses this option to render the "..." sort of adornments wherever an outlining node is collapsed.

Since the adornments that are inserted in place of collapsed regions should be inserted in between the surrounding text characters, intra-text adornments are used.

What you do is have an IIntraTextSpacerTag tagger return the same tag ranges as the ICollapsedRegionTag ranges that need adornments. The text formatter will look for intra-text spacers that match the same range as collapsed ranges and will render space in those locations. Then an intra-text adornment manager can place an adornment in that space.

To sum up, an ICollapsedRegionTag is returned by a tagger over a certain range. An IIntraTextSpacerTag is also returned by a tagger over the same range. An intra-text adornment manager places an adornment in the space that has been reserved.