source: branches/PersistenceOverhaul/HeuristicLab.ExtLibs/HeuristicLab.AvalonEdit/5.0.1/AvalonEdit-5.0.1/Highlighting/HighlightingColorizer.cs

// Copyright (c) 2014 AlphaSierraPapa for the SharpDevelop Team
// 
// Permission is hereby granted, free of charge, to any person obtaining a copy of this
// software and associated documentation files (the "Software"), to deal in the Software
// without restriction, including without limitation the rights to use, copy, modify, merge,
// publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
// to whom the Software is furnished to do so, subject to the following conditions:
// 
// The above copyright notice and this permission notice shall be included in all copies or
// substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
// FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.

using System;
using System.Diagnostics;
using System.Windows.Media;
using ICSharpCode.AvalonEdit.Document;
using ICSharpCode.AvalonEdit.Rendering;

namespace ICSharpCode.AvalonEdit.Highlighting
{
  /// <summary>
  /// A colorizes that interprets a highlighting rule set and colors the document accordingly.
  /// </summary>
  public class HighlightingColorizer : DocumentColorizingTransformer
  {
    readonly IHighlightingDefinition definition;
    TextView textView;
    IHighlighter highlighter;
    bool isFixedHighlighter;
    
    /// <summary>
    /// Creates a new HighlightingColorizer instance.
    /// </summary>
    /// <param name="definition">The highlighting definition.</param>
    public HighlightingColorizer(IHighlightingDefinition definition)
    {
      if (definition == null)
        throw new ArgumentNullException("definition");
      this.definition = definition;
    }
    
    /// <summary>
    /// Creates a new HighlightingColorizer instance that uses a fixed highlighter instance.
    /// The colorizer can only be used with text views that show the document for which
    /// the highlighter was created.
    /// </summary>
    /// <param name="highlighter">The highlighter to be used.</param>
    public HighlightingColorizer(IHighlighter highlighter)
    {
      if (highlighter == null)
        throw new ArgumentNullException("highlighter");
      this.highlighter = highlighter;
      this.isFixedHighlighter = true;
    }
    
    /// <summary>
    /// Creates a new HighlightingColorizer instance.
    /// Derived classes using this constructor must override the <see cref="CreateHighlighter"/> method.
    /// </summary>
    protected HighlightingColorizer()
    {
    }
    
    void textView_DocumentChanged(object sender, EventArgs e)
    {
      TextView textView = (TextView)sender;
      DeregisterServices(textView);
      RegisterServices(textView);
    }
    
    /// <summary>
    /// This method is called when a text view is removed from this HighlightingColorizer,
    /// and also when the TextDocument on any associated text view changes.
    /// </summary>
    protected virtual void DeregisterServices(TextView textView)
    {
      if (highlighter != null) {
        if (isInHighlightingGroup) {
          highlighter.EndHighlighting();
          isInHighlightingGroup = false;
        }
        highlighter.HighlightingStateChanged -= OnHighlightStateChanged;
        // remove highlighter if it is registered
        if (textView.Services.GetService(typeof(IHighlighter)) == highlighter)
          textView.Services.RemoveService(typeof(IHighlighter));
        if (!isFixedHighlighter) {
          if (highlighter != null)
            highlighter.Dispose();
          highlighter = null;
        }
      }
    }
    
    /// <summary>
    /// This method is called when a new text view is added to this HighlightingColorizer,
    /// and also when the TextDocument on any associated text view changes.
    /// </summary>
    protected virtual void RegisterServices(TextView textView)
    {
      if (textView.Document != null) {
        if (!isFixedHighlighter)
          highlighter = textView.Document != null ? CreateHighlighter(textView, textView.Document) : null;
        if (highlighter != null && highlighter.Document == textView.Document) {
          // add service only if it doesn't already exist
          if (textView.Services.GetService(typeof(IHighlighter)) == null) {
            textView.Services.AddService(typeof(IHighlighter), highlighter);
          }
          highlighter.HighlightingStateChanged += OnHighlightStateChanged;
        }
      }
    }
    
    /// <summary>
    /// Creates the IHighlighter instance for the specified text document.
    /// </summary>
    protected virtual IHighlighter CreateHighlighter(TextView textView, TextDocument document)
    {
      if (definition != null)
        return new DocumentHighlighter(document, definition);
      else
        throw new NotSupportedException("Cannot create a highlighter because no IHighlightingDefinition was specified, and the CreateHighlighter() method was not overridden.");
    }
    
    /// <inheritdoc/>
    protected override void OnAddToTextView(TextView textView)
    {
      if (this.textView != null) {
        throw new InvalidOperationException("Cannot use a HighlightingColorizer instance in multiple text views. Please create a separate instance for each text view.");
      }
      base.OnAddToTextView(textView);
      this.textView = textView;
      textView.DocumentChanged += textView_DocumentChanged;
      textView.VisualLineConstructionStarting += textView_VisualLineConstructionStarting;
      textView.VisualLinesChanged += textView_VisualLinesChanged;
      RegisterServices(textView);
    }
    
    /// <inheritdoc/>
    protected override void OnRemoveFromTextView(TextView textView)
    {
      DeregisterServices(textView);
      textView.DocumentChanged -= textView_DocumentChanged;
      textView.VisualLineConstructionStarting -= textView_VisualLineConstructionStarting;
      textView.VisualLinesChanged -= textView_VisualLinesChanged;
      base.OnRemoveFromTextView(textView);
      this.textView = null;
    }
    
    bool isInHighlightingGroup;
    
    void textView_VisualLineConstructionStarting(object sender, VisualLineConstructionStartEventArgs e)
    {
      if (highlighter != null) {
        // Force update of highlighting state up to the position where we start generating visual lines.
        // This is necessary in case the document gets modified above the FirstLineInView so that the highlighting state changes.
        // We need to detect this case and issue a redraw (through OnHighlightStateChanged)
        // before the visual line construction reuses existing lines that were built using the invalid highlighting state.
        lineNumberBeingColorized = e.FirstLineInView.LineNumber - 1;
        if (!isInHighlightingGroup) {
          // avoid opening group twice if there was an exception during the previous visual line construction
          // (not ideal, but better than throwing InvalidOperationException "group already open"
          // without any way of recovering)
          highlighter.BeginHighlighting();
          isInHighlightingGroup = true;
        }
        highlighter.UpdateHighlightingState(lineNumberBeingColorized);
        lineNumberBeingColorized = 0;
      }
    }
    
    void textView_VisualLinesChanged(object sender, EventArgs e)
    {
      if (highlighter != null && isInHighlightingGroup) {
        highlighter.EndHighlighting();
        isInHighlightingGroup = false;
      }
    }
    
    DocumentLine lastColorizedLine;
    
    /// <inheritdoc/>
    protected override void Colorize(ITextRunConstructionContext context)
    {
      this.lastColorizedLine = null;
      base.Colorize(context);
      if (this.lastColorizedLine != context.VisualLine.LastDocumentLine) {
        if (highlighter != null) {
          // In some cases, it is possible that we didn't highlight the last document line within the visual line
          // (e.g. when the line ends with a fold marker).
          // But even if we didn't highlight it, we'll have to update the highlighting state for it so that the
          // proof inside TextViewDocumentHighlighter.OnHighlightStateChanged holds.
          lineNumberBeingColorized = context.VisualLine.LastDocumentLine.LineNumber;
          highlighter.UpdateHighlightingState(lineNumberBeingColorized);
          lineNumberBeingColorized = 0;
        }
      }
      this.lastColorizedLine = null;
    }
    
    int lineNumberBeingColorized;
    
    /// <inheritdoc/>
    protected override void ColorizeLine(DocumentLine line)
    {
      if (highlighter != null) {
        lineNumberBeingColorized = line.LineNumber;
        HighlightedLine hl = highlighter.HighlightLine(lineNumberBeingColorized);
        lineNumberBeingColorized = 0;
        foreach (HighlightedSection section in hl.Sections) {
          if (IsEmptyColor(section.Color))
            continue;
          ChangeLinePart(section.Offset, section.Offset + section.Length,
                         visualLineElement => ApplyColorToElement(visualLineElement, section.Color));
        }
      }
      this.lastColorizedLine = line;
    }
    
    /// <summary>
    /// Gets whether the color is empty (has no effect on a VisualLineTextElement).
    /// For example, the C# "Punctuation" is an empty color.
    /// </summary>
    internal static bool IsEmptyColor(HighlightingColor color)
    {
      if (color == null)
        return true;
      return color.Background == null && color.Foreground == null
        && color.FontStyle == null && color.FontWeight == null;
    }
    
    /// <summary>
    /// Applies a highlighting color to a visual line element.
    /// </summary>
    protected virtual void ApplyColorToElement(VisualLineElement element, HighlightingColor color)
    {
      ApplyColorToElement(element, color, CurrentContext);
    }
    
    internal static void ApplyColorToElement(VisualLineElement element, HighlightingColor color, ITextRunConstructionContext context)
    {
      if (color.Foreground != null) {
        Brush b = color.Foreground.GetBrush(context);
        if (b != null)
          element.TextRunProperties.SetForegroundBrush(b);
      }
      if (color.Background != null) {
        Brush b = color.Background.GetBrush(context);
        if (b != null)
          element.BackgroundBrush = b;
      }
      if (color.FontStyle != null || color.FontWeight != null) {
        Typeface tf = element.TextRunProperties.Typeface;
        element.TextRunProperties.SetTypeface(new Typeface(
          tf.FontFamily,
          color.FontStyle ?? tf.Style,
          color.FontWeight ?? tf.Weight,
          tf.Stretch
        ));
      }
    }
    
    /// <summary>
    /// This method is responsible for telling the TextView to redraw lines when the highlighting state has changed.
    /// </summary>
    /// <remarks>
    /// Creation of a VisualLine triggers the syntax highlighter (which works on-demand), so it says:
    /// Hey, the user typed "/*". Don't just recreate that line, but also the next one
    /// because my highlighting state (at end of line) changed!
    /// </remarks>
    void OnHighlightStateChanged(int fromLineNumber, int toLineNumber)
    {
      if (lineNumberBeingColorized != 0) {
        // Ignore notifications for any line except the one we're interested in.
        // This improves the performance as Redraw() can take quite some time when called repeatedly
        // while scanning the document (above the visible area) for highlighting changes.
        if (toLineNumber <= lineNumberBeingColorized) {
          return;
        }
      }
      
      // The user may have inserted "/*" into the current line, and so far only that line got redrawn.
      // So when the highlighting state is changed, we issue a redraw for the line immediately below.
      // If the highlighting state change applies to the lines below, too, the construction of each line
      // will invalidate the next line, and the construction pass will regenerate all lines.
      
      Debug.WriteLine(string.Format("OnHighlightStateChanged forces redraw of lines {0} to {1}", fromLineNumber, toLineNumber));
      
      // If the VisualLine construction is in progress, we have to avoid sending redraw commands for
      // anything above the line currently being constructed.
      // It takes some explanation to see why this cannot happen.
      // VisualLines always get constructed from top to bottom.
      // Each VisualLine construction calls into the highlighter and thus forces an update of the
      // highlighting state for all lines up to the one being constructed.
      
      // To guarantee that we don't redraw lines we just constructed, we need to show that when
      // a VisualLine is being reused, the highlighting state at that location is still up-to-date.
      
      // This isn't exactly trivial and the initial implementation was incorrect in the presence of external document changes
      // (e.g. split view).
      
      // For the first line in the view, the TextView.VisualLineConstructionStarting event is used to check that the
      // highlighting state is up-to-date. If it isn't, this method will be executed, and it'll mark the first line
      // in the view as requiring a redraw. This is safely possible because that event occurs before any lines are reused.
      
      // Once we take care of the first visual line, we won't get in trouble with other lines due to the top-to-bottom
      // construction process.
      
      // We'll prove that: if line N is being reused, then the highlighting state is up-to-date until (end of) line N-1.
      
      // Start of induction: the first line in view is reused only if the highlighting state was up-to-date
      // until line N-1 (no change detected in VisualLineConstructionStarting event).
      
      // Induction step:
      // If another line N+1 is being reused, then either
      //     a) the previous line (the visual line containing document line N) was newly constructed
      // or  b) the previous line was reused
      // In case a, the construction updated the highlighting state. This means the stack at end of line N is up-to-date.
      // In case b, the highlighting state at N-1 was up-to-date, and the text of line N was not changed.
      //   (if the text was changed, the line could not have been reused).
      // From this follows that the highlighting state at N is still up-to-date.
      
      // The above proof holds even in the presence of folding: folding only ever hides text in the middle of a visual line.
      // Our Colorize-override ensures that the highlighting state is always updated for the LastDocumentLine,
      // so it will always invalidate the next visual line when a folded line is constructed
      // and the highlighting stack has changed.
      
      if (fromLineNumber == toLineNumber) {
        textView.Redraw(textView.Document.GetLineByNumber(fromLineNumber));
      } else {
        // If there are multiple lines marked as changed; only the first one really matters
        // for the highlighting during rendering.
        // However this callback is also called outside of the rendering process, e.g. when a highlighter
        // decides to re-highlight some section based on external feedback (e.g. semantic highlighting).
        var fromLine = textView.Document.GetLineByNumber(fromLineNumber);
        var toLine = textView.Document.GetLineByNumber(toLineNumber);
        int startOffset = fromLine.Offset;
        textView.Redraw(startOffset, toLine.EndOffset - startOffset);
      }
      
      /*
       * Meta-comment: "why does this have to be so complicated?"
       * 
       * The problem is that I want to re-highlight only on-demand and incrementally;
       * and at the same time only repaint changed lines.
       * So the highlighter and the VisualLine construction both have to run in a single pass.
       * The highlighter must take care that it never touches already constructed visual lines;
       * if it detects that something must be redrawn because the highlighting state changed,
       * it must do so early enough in the construction process.
       * But doing it too early means it doesn't have the information necessary to re-highlight and redraw only the desired parts.
       */
    }
  }
}