Step-by-Step Walkthrough

This functionality is the ability for a lexer to tokenize text and use that information to drive syntax highlighting within a SyntaxEditor.

Requires an ILexer feature service and a token tagger provider service. The token tagger (created for each document by the provider service) tags ranges of text as tokens with a certain IClassificationType.

The classification types that are tagged by the token tagger must be mapped to highlighting styles in a highlighting style registry. Generally the AmbientHighlightingStyleRegistry is used for the mappings.

To sum up, the lexer tokenizes text, the token tagger flags ranges of text with tokens/classification types, and the highlighting style registry tells SyntaxEditor how to convert tagged ranges to syntax highlighted markup.

When loading a syntax language from a language definition (.langdef) file, everything described above is configured for you.

While lexers generally provide the core syntax highlighting (via the functionality described above), sometimes you may wish to override the syntax highlighting for certain text ranges, add underlines, change background colors, etc.

To accomplish this a tagger provider service must be used that creates a tagger for IClassificationTag objects. The IClassificationTag interface specifies a IClassificationType. The tagger needs to be set up to be ordered before the TaggerKeys.Token tagger, accomplished via the IOrderable interface, so that its classification types merge into and can override the lexer's existing classifications.

Similar to above, the classification types that are tagged by the tagger must be mapped to highlighting styles in a highlighting style registry. Generally the AmbientHighlightingStyleRegistry is used for the mappings.

The result is that syntax highlighting can be overridden. Multiple layers of customized syntax highlighting can be achieved using this same mechanism.

Syntax and semantic analysis generally include the parsing of tokens to ensure that code is syntactically correct and valid. Parsing kicks off following text changes. Some form of parse data (which can include an AST, error list, etc.) is returned to the document when the parsing completes. The parsing options can be automatically offloaded into a worker thread so that the complex parsing doesn't cause any locking of the main UI thread.

The first step in setting up parsing is to ensure an ambient parse request dispatcher is installed right at your application's startup. This is vital because it is what allows the parsing to occur in a separate worker thread. If no ambient parse request dispatcher is installed, parsing will occur in the main UI thread. This could cause the editor user interface to slow down, depending on how much work the parser does. Therefore, make sure it is installed to prevent any slowdowns.

Next, register an IParser feature service. Now the parser will be called in a worker thread whenever text changes occur to a document that uses the language.

Actipro offers a very robust LL(*) Parser Framework that makes it simple to build IParser-based parsers using EBNF-like notation in C# and VB. It is free to use, has AST construction, error handling, callbacks, and a lot of other features that make it integrate nicely with our core text/parsing framework.

Alternatively, since a parser just has to implement the IParser interface, any sort of custom parsing can be performed with our generic parsing mechanism.

There are free add-ons that come with SyntaxEditor that make it easy to integrate with popular third-party parsers:

• ANTLR Add-on
• Irony Add-on

Automatic outlining is where the document text is scanned, and an outlining node hierarchy is constructed based on its contents. The outlining node tree is rendered visually in the editor's outlining margin and end users can expand/collapse nodes. As further text changes occur, the outlining node tree is incrementally updated.

The IOutliningManager is the object that maintains the outlining node hierarchy. When a language has an IOutliner service registered, the outlining manager knows that the language is capable of performing automatic outlining. The outlining manager uses the outliner service to retrieve an IOutliningSource whenever it needs to update. The outlining source is capable of examining an offset and returning whether an outlining node should start or end there, or neither. There are several base classes included with SyntaxEditor that make it easy to create an outlining source.

An Outliner service is required for automatic outlining support. The Outlining and Collapsing Features series of topics talk about how create outlining sources and define nodes.

The built-in CollapsedRegionQuickInfoProvider service can be registered on a language to allow quick info tips to be automatically displayed when the end user hovers over a collapsed outlining node adornment, such as the "..." blocks.

Line commenting is the ability for SyntaxEditor to comment and uncomment lines with language-specific text. For instance, C# syntax languages can be set up to use // single line comments for line commenting. Or they could be set up to use /* ... */ multi-line comments instead.

This feature requires that an ILineCommenter service be registered with the language.

Text statistics can be quickly constructed for any language. The statistics can include everything from word counts to readability scores. Custom statistics can be built for each language.

This feature requires that an ITextStatisticsFactory service be registered with the language.

While many syntax languages use the same patterns for determining line breaks, there are some syntax languages that require further customization. For instance, the CSS syntax language needs hyphen (-) characters to be considered word characters.

Custom word break finding functionality can be configured for a language by registering an IWordBreakFinder service with the language.

IntelliPrompt Completion is an extremely helpful way for end users to maximize their productivity when writing code. Completion sessions support auto-complete via keys like Ctrl+Space and will show a completion list popup when no single auto-completion can be determined.

The IntelliPrompt Completion topic walks through the very extensive list of features available with completion sessions.

Syntax languages have several ways they can be set up to provide automated IntelliPrompt completion.

One or more ICompletionProvider services may be registered on the language. These provider services can be ordered. When a completion provider service is on the language, any Ctrl+Space keys typed by the end user will call the first completion provider to see if it can open a completion session. If it can't, the next provider is checked, and so on. When opening a session, the completion providers determine if auto-complete is allowed, what features are enabled (filtering, auto-shrink, text matching algorithms, etc.). The completion provider must also populate the items in the completion session prior to opening it. Completion providers often use a mix of looking at any available document ParseData and token scanning to determine which sort of items should be in the session, based on the current editor view caret location.

Completion sessions can also be requested when the end user begins to type a new word. This involves having the language register an IEditorDocumentTextChangeEventSink service and in the text changed event notification, check a helper property on the event arguments that indicates if a new word is being typed. If so, request a completion session. A full sample of this is included in the "Opening a Session in Response to a Typed Character" section of the Completion List topic.

IntelliPrompt Quick Info is the ability to render helpful tooltips related to end user mouse hovers, or related to what is under the caret. The content of a quick info tip can be plain text, formatted text (using an HTML-like markup), or any UIElement.

The IntelliPrompt Quick Info topic walks through the list of features available with quick info sessions.

One or more IQuickInfoProvider services may be registered on the language. These provider services can be ordered. When a quick info provider service is on the language, any mouse hovers by the end user will call the first quick info provider to see if it can open a quick info session. If it can't, the next provider is checked, and so on. The quick info provider populates content in the quick info session prior to it opening. Similar to completion providers, quick info providers often use a mix of looking at any available document ParseData and token scanning to detemine the content that should be presented in the session.

A Navigable Symbol Selector control is included that can be bound to a SyntaxEditor and supports listing accessible symbols (such as types and members) within a document. The selections within the control update as the editor caret is moved. When a symbol is selected from a dropdown, the caret navigates directly to the related symbol declaration.

The control requires that a feature service is implemented on the language that returns accessible symbols. The IntelliPrompt Navigable Symbol Provider topic walks through how to create such a service.

IntelliPrompt Code Snippets allow small snippets of code to be inserted into a document. Selection sessions display all available code snippets and allow the end user to easily pick one to activate. Template sessions occur when a code snippet is activated and allow the end user to Tab between pre-defined fields within the code snippet to customize the text that is inserted.

Code snippet features require that an IntelliPrompt code snippet provider is registered on the language, with one or more code snippets loaded into it.

A custom tagger can be installed into a document by using a tagger provider language service. Once the tagger is installed into the document, tag aggregators for the tag type returned by the tagger will be collected from the tagger and combined with results from other similar taggers.

Custom taggers are often used to drive features like customized syntax highlighting, squiggle line display, adornments, etc.

If you are using an IParser feature service on your language, it will return resulting parse data to the ICodeDocument.ParseData property. If the parse data object implements the IParseErrorProvider interface then parse errors can be retrieved from it.

There is a built-in tagger called ParseErrorTagger that can be attached to a document via a document-oriented tagger provider service. See the Tagger Provider topic for details on making tagger provider services.

When this parse error tagger is attached to a document, it will monitor the document's parse data for changes. If the parse data is updated, it will automatically get the list of parse errors from it (assuming the parse data implements IParseErrorProvider) and will return ISquiggleTag tags for each one. This automatically drives the squiggle line display when used in an editor.

The SquiggleTagQuickInfoProvider is an IQuickInfoProvider that presents a Quick Info popup with the contents of ISquiggleTag.ContentProvider. When registered with a language along with a ParseErrorTagger, it will provide the description of a parsing error when you hover the mouse over a text range that is tagged by an ISquiggleTag.

An example of adornments that are not related directly to document text content are alternating row highlights. To implement this sort of feature, a custom adornment manager is created that inherits AdornmentManagerBase. The manager attaches to the view's TextAreaLayout event and updates its Rectangle higlight adornments based on the document line numbers of the view lines that need adornments.

An adornment manager provider service is required to create adornment manager instances for each view that should use them.

An example of adornments that are related directly to text spans are borders around certain text ranges that indicate find operation results. For scenarios like this, a custom adornment manager is created that inherits DecorationAdornmentManagerBase<T, U>. The base class handles the determination of when to add/update/remove adornments. When a new adornment needs to be added, the AddAdornment method is called. This method is overridden in your inheriting class and the code you implement calls IAdornmentLayer.AddAdornment to add an adornment to the layer.

An adornment manager provider service is required to create adornment manager instances for each view that should use them.

Any sort of content can be inserted in-line with text, right between text characters. This feature is known as intra-text adornments. The content could be images, controls, or any other UI element.

See the Intra-Text Adornments topic for details on how to use this feature.

Sometimes you may wish to hide a region of text within a SyntaxEditor view but still keep it in the document. This sort of feature can be attained by "tagging" the desired ranges to hide with ICollapsedRegionTag instances. This feature can be used independently from code outlining. In fact, the code outlining feature does use this behind the scenes for collapsed nodes. If you tag the same collapsed regions with an IIntraTextSpacerTag, you can insert an adornment in place of the collapsed region.

See the Collapsing Regions without Outlining topic for details on how to use this feature.

There are a large number of events to which languages can be attached, everything from document text changes to end user input. Events are logically grouped into various event sink services.

Any service registered on a language that implements one of the event sink interfaces is automatically notified whenever a related event occurs.

Auto-indent is the ability for SyntaxEditor to automatically indent a new line when the Enter key is pressed. The default behavior is to indent a new line to the same level as the preceding line.

To override the default behavior, an IIndentProvider service must be registered with the language.

Text formatting is the ability for SyntaxEditor to format the text in a specified range where whitespace and other symbols such as braces are adjusted to make code more readable.

See the Text Formatter topic for more information.

Structure matching is the ability for SyntaxEditor to find a bracket or other text delimiter that is related to the delimiter that is next to the caret.

See the Structure Matcher topic for more information.

Delimiter highlighting renders highlights behind delimiter pairs that are currently next to the caret, also known as bracket highlighting.

While the delimiter highlighting feature requires the use of a structure matcher (see above), it also requires that another language service is registered that can tag delimiter highlight ranges.

See the Delimiter Highlighting topic for more information.

Code block selection adjusts the view's selection by expanding it to include containing code blocks and contracting all the way back down to the caret as appropriate.

See the Code Block Selection topic for more information.

An auto-corrector can perform additional edits after text changes, such as auto-case correcting language keywords.

See the Auto-Corrector topic for more information.

Delimiter auto-completion is where the user types a start delimiter and a related end delimiter is auto-inserted after the caret.

See the Delimiter Auto-Completer topic for more information.