Tags and Classification Types
Tags are objects that store data and can be applied to a text range. Classification types are used throughout the product to categorize objects. Both are key pieces towards understanding tagging.
What are Tags?
Tags are any object inheriting ITag that can contain some data and can be applied to and tracked with a range of text in a document.
There are several built-in tag types used to drive various functionality pieces in the product. This table lists the built-in tag interface types that are supported, along with optional implementation classes that can be used.
| Type | Description |
|---|---|
|
A tag that refers to an IClassificationType and can be used to classify a range of text (see below), which when used in an editor can also drive syntax highlighting. The ClassificationTag class implements this tag interface. |
|
|
A tag that can mark a range of text as read-only (uneditable) by the end user. This is similar to setting the ITextDocument.IsReadOnly property to Normally, only text changes that overlap (cross) the read-only region will be blocked. The IReadOnlyRegionTag.IncludeFirstEdge property can be set to The ReadOnlyRegionTag class implements this tag interface and also includes an IClassificationType reference, which defaults to ClassificationTypes.ReadOnlyRegion. If that classification type is registered with a style in the ambient highlighting style registry, it is possible for the read-only regions to render in an alternate appearance, such as with a gray background. |
|
|
A tag that may be available when the text/parsing framework is used in conjunction with an editor. In that case, the tag can mark a range of text as needing a squiggle underline. This is generally used to flag syntax errors, etc. The tag includes an IClassificationType reference so that the type of squiggle can be classified. The SquiggleTag class implements this tag interface. |
|
|
A tag that refers to an IToken and can be used to mark a range of text with the token. Use of these tags allow snapshot readers to scan through a document by token. Token tags are typically handled completely internally by the text/parsing framework via the use of token taggers. |
|
|
A tag that indicates a text range is unused, such as when the code can safely be removed or will never execute. Text ranges tagged with this tag will render with their normal syntax highlighting colors, but with reduced opacity. This feature is described in more detail in the Syntax Highlighting topic. |
Classification Types
The IClassificationType interface provides information about classification types. A classification type is a high-level categorization, such as Identifier or Comment, that can be applied to text ranges via tags.
Each IClassificationType defines a string-based Key that identifies it, along with a more descriptive Description that may be used in user interfaces.
Tip
Several of the most common classification types are available via static properties on the ClassificationTypes class.
The reuse of IClassificationType instances is highly recommended.
Tokens vs. Classifications
Tokens and classification tags are often related, especially in the case of token taggers. Let us examine an example.
In a C# document, consider a token that has been created via lexing for the keyword foreach. Syntax languages (advanced ones at least) generally assign different token ID values for each individual keyword. For instance, the token ID for keyword foreach could be 50. This value is likely defined in some enumeration or static class of integer constants for the C# language. By doing this, when we later scan the tokens in the document, we know that this particular token is a foreach token without having to look at its text.
Now assume that a classification tag has been applied over the same text range via a token tagger. This classification would apply a Keyword classification type over that text range.
The difference is that where a token can be very specific as to what it represents, a classification tag over the same range is usually much more general. When the text/parsing framework is used within an editor control such as SyntaxEditor, classification tags are what drive syntax highlighting. In that scenario, each classification type is associated with a highlighting style. Therefore, when ranges of text are classified with a classification type, SyntaxEditor maps the classification type to its related highlighting style and renders the text in the range using that style.
Even though token taggers most often provide both ITokenTag and IClassificationTag instances, additional IClassificationTag taggers can be layered on top of a token tagger to override and reclassify text. When used in an editor, this allows for more customized syntax highlighting to be added that merges with the default syntax highlighting.
Providing Tagged Ranges
Taggers are objects that can return an enumerable of tagged snapshot ranges that overlap a requested set of snapshot ranges. They are described in detail in the Taggers topic, along with details on special token taggers.