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 */
25package javax.swing.text;
26
27import java.awt.Color;
28import java.awt.Graphics;
29import 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 */
37public 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};
155