KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > editor > highlighting > HighlightsContainer


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.spi.editor.highlighting;
21
22 import javax.swing.text.Position JavaDoc;
23
24 /**
25  * The container of highlighted areas and their attributes.
26  *
27  * @author vita
28  */
29 public interface HighlightsContainer {
30
31     /**
32      * The attribute key for highlights that need to span across a whole line.
33      *
34      * <p>Typically highlights only affect rendering of a small part of text
35      * (perhaps just several characters). Some layers, however, need to highlight
36      * a whole line in an editor window regardless of how much text the line
37      * contains. The highlighting of a line with a caret is an example of such a layer.
38      *
39      * <p>If you want a highlight that spans accross the whole editor pane you
40      * can add this attribute key to the highlight's <code>AttributeSet</code>
41      * and set its value to <code>Boolean.TRUE</code>. The highlighted area must
42      * contain the new-line character at the end of the line.
43      */
44     static final String JavaDoc ATTR_EXTENDS_EOL = new String JavaDoc("org.netbeans.spi.editor.highlighting.HighlightsContainer.ATTR_EXTENDS_EOL"); //NOI18N
45
46     /**
47      * The attribute key for highlights that need to show up on empty lines.
48      *
49      * <p>If you use this key for a highlight which contains the new-line character
50      * at the end of an empty line and set the value of this attribute to
51      * <code>Boolean.TRUE</code> then the highlight will be drawn as
52      * a half-character-wide stripe at the beginning of the line.
53      */
54     static final String JavaDoc ATTR_EXTENDS_EMPTY_LINE = new String JavaDoc("org.netbeans.spi.editor.highlighting.HighlightsContainer.ATTR_EXTENDS_EMPTY_LINE"); //NOI18N
55
56     /**
57      * Provides the list of highlighted areas that should be used for rendering
58      * a document.
59      *
60      * <p>The returned highlighted areas (highlights) must obey the following rules:
61      * <ul>
62      * <li>The starting and ending offsets of each highlight should be
63      * within the range specified by the <code>startOffset</code> and <code>endOffset</code>
64      * parameters. Any highlights outside of this range will be clipped by the
65      * rendering infrastructure.
66      * <li>The highlights must not overlap. The infrastructure may ignore or trim
67      * any overlapping highlights.
68      * <li>The list of highlights must be sorted by their
69      * starting offsets ascendingly (i.e. the smallest offset first).
70      * </ul>
71      *
72      * <p>The editor infrastructure will log any problems it may encounter with
73      * provided implementations of this interface. Although the infrastructure
74      * will try to do its best to render all highlights supplied by the implementors,
75      * if the above rules are violated the results can't be garanteed.
76      *
77      * @param startOffset The starting offset of the area which the caller
78      * attempts to repaint (or create views for). The staring offset is always >=0.
79      * @param endOffset The ending offset of the rendered area. The <code>Integer.MAX_VALUE</code>
80      * can be passed in if the end offset is unknown to the caller.
81      * The highlights container is then expected to return all highlights
82      * up to the end of the document.
83      *
84      * @return non-null iterator of highlights sorted by offsets.
85      */
86     HighlightsSequence getHighlights(int startOffset, int endOffset);
87     
88     /**
89      * Adds a listener to this highlights container.
90      *
91      * @param listener The listener to add.
92      */
93     void addHighlightsChangeListener(HighlightsChangeListener listener);
94     
95     /**
96      * Removes a listener from this highlights container.
97      *
98      * @param listener The listener to remove.
99      */
100     void removeHighlightsChangeListener(HighlightsChangeListener listener);
101     
102 }
103
Popular Tags