Syntax coloring is provided in the platform text framework using a model of damage, repair, and reconciling. For each change applied to a document, a presentation reconciler determines which region of the visual presentation should be invalidated and how to repair it. Different strategies can be used for different content types in the document.
Implementing syntax coloring (and doing so with a presentation reconciler) is optional. By default, SourceViewerConfiguration does not install a presentation reconciler since it does not know the document model used for a particular editor, and has no generic behavior for syntax highlighting.
In order to use the reconciling classes to implement syntax highlighting, your editor's source viewer configuration must be configured to define a presentation reconciler. Once again, we start with JavaSourceViewerConfiguration to see how a presentation reconciler is defined for our editor.
public IPresentationReconciler getPresentationReconciler(ISourceViewer sourceViewer) {
PresentationReconciler reconciler= new PresentationReconciler();
...
return reconciler;
}
To understand what a presentation reconciler does, we must first look at the concepts of damage, repair, and reconciling.
As the user modifies text in an editor, parts of the editor must be redisplayed to show the changes. Computing the text that must be redisplayed is known as computing damage. When syntax coloring is involved, the amount of damage caused by an editing operation becomes more extensive, since the presence or absence of a single character could change the coloring of the text around it.
Damagers (IPresentationDamager) determine the region of a document's presentation which must be rebuilt because of a document change. A presentation damager is assumed to be specific to a particular document content type (or region). It must be able to return a damage region that is valid input for a presentation repairer (IPresentationRepairer). A repairer must be able to derive all of the information it needs from a damage region in order to successfully describe the repairs that are needed for a particular content type.
Reconciling describes the overall process of maintaining the presentation of a document as changes are made in the editor. A presentation reconciler (IPresentationReconciler) monitors changes to the text through its associated viewer. It uses the document's regions to determine the content types affected by the change and notifies a damager that is appropriate for the affected content type. Once the damage is computed, it is passed to the appropriate repairer which will construct repair descriptions that are applied to the viewer to put it back in sync with the underlying content.
The classes in org.eclipse.jface.text.reconciler define additional support classes for synchronizing a document model with external manipulation of the document.
Presentation reconcilers should be provided with a repairer and damager pair for each content type to be found in the document. It is up to each editor to determine the appropriate implementation for a presentation reconciler. However, the platform provides support in org.eclipse.jface.text.rules for using rule-based document scanners to compute and repair damage. Default damagers and repairers are defined in this package. They can be used along with the standard reconcilers in org.eclipse.jface.text.presentation to implement syntax coloring by defining scanning rules for the document.
Now we have enough background to look in detail at the creation of the example presentation reconciler. Recall that the Java editor example implements a JavaPartitionScanner which partitions the document into content types representing javadoc, multi line comments, and everything else.
For each of these content types, a damager/repairer pair must be specified. This is done below using the PresentationReconciler and the DefaultDamagerRepairer.
JavaColorProvider provider= JavaEditorEnvironment.getJavaColorProvider(); PresentationReconciler reconciler= new PresentationReconciler(); DefaultDamagerRepairer dr= new DefaultDamagerRepairer(JavaEditorEnvironment.getJavaCodeScanner()); reconciler.setDamager(dr, IDocument.DEFAULT_CONTENT_TYPE); reconciler.setRepairer(dr, IDocument.DEFAULT_CONTENT_TYPE); dr= new DefaultDamagerRepairer(new SingleTokenScanner(new TextAttribute(provider.getColor(JavaColorProvider.JAVADOC_DEFAULT)))); reconciler.setDamager(dr, JavaPartitionScanner.JAVA_DOC); reconciler.setRepairer(dr, JavaPartitionScanner.JAVA_DOC); dr= new DefaultDamagerRepairer(new SingleTokenScanner(new TextAttribute(provider.getColor(JavaColorProvider.MULTI_LINE_COMMENT)))); reconciler.setDamager(dr, JavaPartitionScanner.JAVA_MULTILINE_COMMENT); reconciler.setRepairer(dr, JavaPartitionScanner.JAVA_MULTILINE_COMMENT); return reconciler;
Note that the example provide scanners for each content type.
The default content type is set up with a JavaCodeScanner so that keywords can be detected and colored. The JavaCodeScanner builds rules for detecting different kinds of tokens, such as single line comments, white space, and words. It describes the colors that should be used for words of different token types.
The other content types are set up with a SingleTokenScanner and given a color to be used for tokens in these content types.
All of the details for damaging and repairing the proper parts of the documents according to the scanning rules are handled by DefaultDamagerRepairer. These details typically don't need to be understood by plug-in code. Your plug-in should focus on building a set of rules that are appropriate for partitioning and scanning its editor content.
The Java editor example provides a subclass of SourceViewerConfiguration for installing the presentation reconciler as seen earlier. A presentation reconciler can also be installed dynamically on a text viewer using IPresentationReconciler protocol. There is no particular runtime benefit to doing it either way, but putting all of the pluggable behavior overrides in a subclass of SourceViewerConfiguration provides the advantage of consolidating all of the behavioral overrides in one place. The dynamic protocol may be useful when different presentation reconcilers are attached to a viewer throughout the life of an editor.