1 /*
   2  * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing.text;
  26 
  27 import java.awt.Color;
  28 import java.awt.Graphics;
  29 import java.awt.Shape;
  30 
  31 /**
  32  * An interface for an object that allows one to mark up the background
  33  * with colored areas.
  34  *
  35  * @author  Timothy Prinzing
  36  */
  37 public interface Highlighter {
  38 
  39     /**
  40      * Called when the UI is being installed into the
  41      * interface of a JTextComponent.  This can be used
  42      * to gain access to the model that is being navigated
  43      * by the implementation of this interface.
  44      *
  45      * @param c the JTextComponent editor
  46      */
  47     public void install(JTextComponent c);
  48 
  49     /**
  50      * Called when the UI is being removed from the
  51      * interface of a JTextComponent.  This is used to
  52      * unregister any listeners that were attached.
  53      *
  54      * @param c the JTextComponent editor
  55      */
  56     public void deinstall(JTextComponent c);
  57 
  58     /**
  59      * Renders the highlights.
  60      *
  61      * @param g the graphics context.
  62      */
  63     public void paint(Graphics g);
  64 
  65     /**
  66      * Adds a highlight to the view.  Returns a tag that can be used
  67      * to refer to the highlight.
  68      *
  69      * @param p0 the beginning of the range >= 0
  70      * @param p1 the end of the range >= p0
  71      * @param p the painter to use for the actual highlighting
  72      * @return an object that refers to the highlight
  73      * @exception BadLocationException for an invalid range specification
  74      */
  75     public Object addHighlight(int p0, int p1, HighlightPainter p) throws BadLocationException;
  76 
  77     /**
  78      * Removes a highlight from the view.
  79      *
  80      * @param tag  which highlight to remove
  81      */
  82     public void removeHighlight(Object tag);
  83 
  84     /**
  85      * Removes all highlights this highlighter is responsible for.
  86      */
  87     public void removeAllHighlights();
  88 
  89     /**
  90      * Changes the given highlight to span a different portion of
  91      * the document.  This may be more efficient than a remove/add
  92      * when a selection is expanding/shrinking (such as a sweep
  93      * with a mouse) by damaging only what changed.
  94      *
  95      * @param tag  which highlight to change
  96      * @param p0 the beginning of the range >= 0
  97      * @param p1 the end of the range >= p0
  98      * @exception BadLocationException for an invalid range specification
  99      */
 100     public void changeHighlight(Object tag, int p0, int p1) throws BadLocationException;
 101 
 102     /**
 103      * Fetches the current list of highlights.
 104      *
 105      * @return the highlight list
 106      */
 107     public Highlight[] getHighlights();
 108 
 109     /**
 110      * Highlight renderer.
 111      */
 112     public interface HighlightPainter {
 113 
 114         /**
 115          * Renders the highlight.
 116          *
 117          * @param g the graphics context
 118          * @param p0 the starting offset in the model >= 0
 119          * @param p1 the ending offset in the model >= p0
 120          * @param bounds the bounding box for the highlight
 121          * @param c the editor
 122          */
 123         public void paint(Graphics g, int p0, int p1, Shape bounds, JTextComponent c);
 124 
 125     }
 126 
 127     /**
 128      * A highlight.
 129      */
 130     public interface Highlight {
 131 
 132         /**
 133          * Gets the starting model offset for the highlight.
 134          *
 135          * @return the starting offset >= 0
 136          */
 137         public int getStartOffset();
 138 
 139         /**
 140          * Gets the ending model offset for the highlight.
 141          *
 142          * @return the ending offset >= 0
 143          */
 144         public int getEndOffset();
 145 
 146         /**
 147          * Gets the painter for the highlighter.
 148          *
 149          * @return the painter
 150          */
 151         public HighlightPainter getPainter();
 152 
 153     }
 154 };