HighlightsSequence


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 java.util.NoSuchElementException  ;
23  import javax.swing.text.AttributeSet  ;
24  import javax.swing.text.Position  ;
25  
26  /**
27   * An iterator through highlights in a <code>HighlightsContainer</code>.
28   *
29   * <p><b>Implementation:</b> Any <code>HighlightsSequence</code> obtained from any of the classes in
30   * the Highlighting API will behave as so called <i>fast-fail</i> iterator. It
31   * means that it will throw <code>ConcurrentModificationException</code> from
32   * its methods if the underlying data (highlights) have changed since when the instance
33   * of the <code>HighlightsSequence</code> was obtained.
34   * 
35   * @author Miloslav Metelka
36   * @version 1.00
37   */
38  
39  public interface HighlightsSequence {
40  
41      /**
42       * An empty <code>HighlightsSequence</code>.
43       */
44      public static final HighlightsSequence EMPTY = new HighlightsSequence() {
45          public boolean moveNext() {
46              return false;
47          }
48  
49          public int getStartOffset() {
50              throw new NoSuchElementException  ();
51          }
52  
53          public int getEndOffset() {
54              throw new NoSuchElementException  ();
55          }
56  
57          public AttributeSet   getAttributes() {
58              throw new NoSuchElementException  ();
59          }
60      }; // End of EMPTY HighlightsSequence
61      
62      /**
63       * Moves the internal pointer to the next highlight in this sequence (if there is any).
64       * If this method returns <code>true</code> highlight's boundaries and attributes
65       * can be retrieved by calling the getter methods.
66       *
67       * @return <code>true</code> If there is a highlight available and it is safe
68       *         to call the getters.
69       * @throws ConcurrentModificationException If the highlights this sequence is
70       *         iterating through have been changed since the creation of the sequence.
71       */
72      boolean moveNext();
73      
74      /**
75       * Gets the start offset of a current highlight.
76       *
77       * @return The offset in a document where the current highlight starts.
78       * @throws ConcurrentModificationException If the highlights this sequence is
79       * iterating through have been changed since the creation of the sequence.
80       */
81      int getStartOffset();
82      
83      /**
84       * Gets the end offset of a current highlight.
85       *
86       * @return The offset in a document where the current highlight ends.
87       * @throws ConcurrentModificationException If the highlights this sequence is
88       * iterating through have been changed since the creation of the sequence.
89       */
90      int getEndOffset();
91      
92      /**
93       * Gets the set of attributes that define how to render a current highlight.
94       * 
95       * <p>Since the <code>AttributeSet</code> can contain any attributes implementors
96       * must be aware of whether the attributes returned from this method affect
97       * metrics or not and set the <code>isFixedSize</code> parameter appropriately
98       * when createing <code>HighlightsLayer</code>s.
99       *
100      * @return The set of text rendering attributes. Must not return <code>null</code>.
101      * @throws ConcurrentModificationException If the highlights this sequence is
102      * iterating through have been changed since the creation of the sequence.
103      * 
104      * @see org.netbeans.spi.editor.highlighting.HighlightsLayer
105      */
106     AttributeSet   getAttributes();
107 }
108
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags