platform/lang-api/src/com/intellij/codeInsight/highlighting/HighlightManager.java

/*
 * Copyright 2000-2009 JetBrains s.r.o.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.intellij.codeInsight.highlighting;

import com.intellij.openapi.editor.Editor;
import com.intellij.openapi.editor.markup.RangeHighlighter;
import com.intellij.openapi.editor.markup.TextAttributes;
import com.intellij.openapi.project.Project;
import com.intellij.psi.PsiElement;
import com.intellij.psi.PsiReference;
import org.intellij.lang.annotations.MagicConstant;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.awt.*;
import java.util.Collection;

/**
 * Allows to highlight areas of text and occurrences of PSI elements in the editor, and to remove the highlighting automatically
 * by some condition.
 *
 * @author max
 */
public abstract class HighlightManager {
  public static HighlightManager getInstance(Project project) {
    return project.getComponent(HighlightManager.class);
  }

  /**
   * Specifies that a highlighter added with {@link #addOccurrenceHighlight} should be removed when the user presses Esc.
   */
  public static final int HIDE_BY_ESCAPE = 0x01;

  /**
   * Specifies that a highlighter added with {@link #addOccurrenceHighlight} should be removed when the user presses any key.
   */
  public static final int HIDE_BY_ANY_KEY = 0x02;

  /**
   * Specifies that a highlighter added with {@link #addOccurrenceHighlight} should be removed when the editor text is changed.
   */
  public static final int HIDE_BY_TEXT_CHANGE = 0x04;

  @MagicConstant(flags = {HIDE_BY_ESCAPE, HIDE_BY_ANY_KEY, HIDE_BY_TEXT_CHANGE})
  public @interface HideFlags {}

  /**
   * Highlights a specified range of text in an editor. The highlighting is removed when the user presses the Esc key, and optionally
   * when the editor text is changed. If the highlighter added by this method needs to be removed
   * manually, {@link #removeSegmentHighlighter} must be used for that.
   *
   * @param editor           the editor in which the highlighting is performed.
   * @param startOffset      the start offset of the text range to highlight.
   * @param endOffset        the end offset of the text range to highlight.
   * @param attributes       the attributes to highlight the text with.
   * @param hideByTextChange if true, the highlighting is removed automatically if the editor text is changed.
   * @param outHighlighters  if not null, the created {@link RangeHighlighter} object is added to this collection.
   */
  public abstract void addRangeHighlight(@NotNull Editor editor,
                                         int startOffset,
                                         int endOffset,
                                         @NotNull TextAttributes attributes,
                                         boolean hideByTextChange,
                                         @Nullable Collection<RangeHighlighter> outHighlighters);

  /**
   * Highlights a specified range of text in an editor. The highlighting is removed when the user presses the Esc key or (optionally)
   * any other key, and optionally when the editor text is changed. If the highlighter added by this method needs to be removed
   * manually, {@link #removeSegmentHighlighter} must be used for that.
   *
   * @param editor           the editor in which the highlighting is performed.
   * @param startOffset      the start offset of the text range to highlight.
   * @param endOffset        the end offset of the text range to highlight.
   * @param attributes       the attributes to highlight the text with.
   * @param hideByTextChange if true, the highlighting is removed automatically if the editor text is changed.
   * @param hideByAnyKey     if true, the highlighting is removed automatically when the user presses any key.
   * @param highlighters     if not null, the created {@link RangeHighlighter} object is added to this collection.
   */
  public abstract void addRangeHighlight(@NotNull Editor editor,
                                         int startOffset,
                                         int endOffset,
                                         @NotNull TextAttributes attributes,
                                         boolean hideByTextChange,
                                         boolean hideByAnyKey,
                                         @Nullable Collection<RangeHighlighter> highlighters);

  /**
   * Removes a range highlighter added by {@link #addRangeHighlight} or another method in this class.
   *
   * @param editor      the editor in which the highlighter should be removed.
   * @param highlighter the highlighter to remove.
   * @return true if the remove was successful, false if the highlighter was not found in the editor.
   */
  public abstract boolean removeSegmentHighlighter(@NotNull Editor editor, @NotNull RangeHighlighter highlighter);

  /**
   * Highlights the text ranges of the specified references in the specified editor. The highlighting is removed when the user presses
   * the Esc key, and optionally when the editor text is changed.
   *
   * @param editor           the editor in which the highlighting is performed.
   * @param occurrences      the references to highlight.
   * @param attributes       the attributes to highlight the text with.
   * @param hideByTextChange if true, the highlighting is removed automatically if the editor text is changed.
   * @param outHighlighters  if not null, the created {@link RangeHighlighter} objects are added to this collection.
   */
  public abstract void addOccurrenceHighlights(@NotNull Editor editor,
                                               @NotNull PsiReference[] occurrences,
                                               @NotNull TextAttributes attributes,
                                               boolean hideByTextChange,
                                               @Nullable Collection<RangeHighlighter> outHighlighters);

  /**
   * Highlights the text ranges of the specified elements in the specified editor. The highlighting is removed when the user presses
   * the Esc key, and optionally when the editor text is changed.
   *
   * @param editor           the editor in which the highlighting is performed.
   * @param elements         the elements to highlight.
   * @param attributes       the attributes to highlight the text with.
   * @param hideByTextChange if true, the highlighting is removed automatically if the editor text is changed.
   * @param outHighlighters  if not null, the created {@link RangeHighlighter} objects are added to this collection.
   */
  public abstract void addOccurrenceHighlights(@NotNull Editor editor,
                                               @NotNull PsiElement[] elements,
                                               @NotNull TextAttributes attributes,
                                               boolean hideByTextChange,
                                               @Nullable Collection<RangeHighlighter> outHighlighters);

  /**
   * Highlights a specified range of text in an editor and optionally adds a mark on the gutter. The highlighting is optionally removed
   * when the user presses the Esc key or any key, or when the editor text is changed. If the highlighter added by this method needs
   * to be removed manually, {@link #removeSegmentHighlighter} must be used for that.
   *
   * @param editor           the editor in which the highlighting is performed.
   * @param start            the start offset of the text range to highlight.
   * @param end              the end offset of the text range to highlight.
   * @param attributes       the attributes to highlight the text with.
   * @param flags            the flags specifying when the highlighting is removed (a combination of
   *                         {@link #HIDE_BY_ESCAPE}, {@link #HIDE_BY_ANY_KEY} and {@link #HIDE_BY_TEXT_CHANGE}).
   * @param outHighlighters  if not null, the created {@link RangeHighlighter} object is added to this collection.
   * @param scrollmarkColor  if not null, a gutter mark with the specified color is added in addition to the editor highlight.
   */
  public abstract void addOccurrenceHighlight(@NotNull Editor editor,
                                              int start,
                                              int end,
                                              TextAttributes attributes,
                                              @HideFlags int flags,
                                              @Nullable Collection<RangeHighlighter> outHighlighters,
                                              @Nullable Color scrollmarkColor);

  /**
   * @deprecated Use {@link #addOccurrenceHighlights(com.intellij.openapi.editor.Editor, com.intellij.psi.PsiElement[], com.intellij.openapi.editor.markup.TextAttributes, boolean, java.util.Collection)} instead (it does the same thing).
   */
  public abstract void addElementsOccurrenceHighlights(@NotNull Editor editor,
                                                       @NotNull PsiElement[] elements,
                                                       @NotNull TextAttributes attributes,
                                                       boolean hideByTextChange,
                                                       @Nullable Collection<RangeHighlighter> outHighlighters);
}