Lines


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  package org.netbeans.core.output2;
20  
21  import org.openide.windows.OutputListener;
22  
23  import javax.swing.event.ChangeListener  ;
24  import java.io.IOException  ;
25  import java.util.regex.Matcher  ;
26  
27  /**
28   * An interface representing the data written to an OutWriter, in terms of lines of text, with
29   * methods for handling line wrapping.
30   */
31  public interface Lines {
32      /**
33       * Get an array of all line numbers which have associated OutputListeners
34       * @return an array of line numbers
35       */
36      int[] allListenerLines();
37  
38      /**
39       * Get the length, in characters, of a given line index
40       *
41       * @param idx the line number
42       * @return the length
43       */
44      int length (int idx);
45  
46      /**
47       * Get the character position corresponding to the start of a line
48       *
49       * @param line A line number
50       * @return The character in the total text at which this line starts
51       */
52      int getLineStart (int line);
53  
54      /**
55       * Get the line index of the nearest line start to this character position in the
56       * entire stored text
57       * @param position
58       * @return The line on which this character position occurs
59       */
60      int getLineAt (int position);
61  
62      /**
63       * Get the number of lines in the stored text
64       * @return A line count
65       */
66      int getLineCount();
67  
68      /**
69       * Get the output listener associated with this line
70       *
71       * @param line A line number
72       * @return An OutputListener, as passed to OutputWriter.println(), or null if no listener
73       *  is associated with this line
74       */
75      OutputListener getListenerForLine (int line);
76  
77      /**
78       * Get the index of the first line which has a listener
79       * @return A line number, or -1 if there are no listeners
80       */
81      int firstListenerLine ();
82      
83      /**
84       * Get the index of the first line which has an important listener
85       * @return A line number, or -1 if there are no important listeners
86       */
87      
88      int firstImportantListenerLine();
89      
90      boolean isImportantHyperlink(int line);
91  
92      /**
93       * Get the nearest listener to the passed line index
94       * @param line A line number
95       * @param backward If it should search up the text
96       * @return A line number, or -1
97       */
98      int nearestListenerLine (int line, boolean backward);
99  
100     /**
101      * Get the length of the longest line in the storage
102      * @return The longest line's length
103      */
104     int getLongestLineLength();
105 
106     /**
107      * Get the count of logical (wrapped) lines above the passed index.  The passed index should be a line
108      * index in a physical coordinate space in which lines are wrapped at charCount.  It will return the
109      * number of logical (wrapped) lines above this line.
110      *
111      * @param logicalLine A line index in wrapped, physical space
112      * @param charCount The number of characters at which line wrapping happens
113      * @return The number of  logical lines above this one.
114      */
115     int getLogicalLineCountAbove (int logicalLine, int charCount);
116 
117     /**
118      * Get the total number of logical lines required to display the stored text if wrapped at the specified
119      * character count.
120      * @param charCount The number of characters at which line wrapping happens
121      * @return The number of logical lines needed to fit all of the text
122      */
123     int getLogicalLineCountIfWrappedAt (int charCount);
124 
125     /**
126      * Determine if a character position indicates the first character of a line.
127      *
128      * @param chpos A character index in the stored text
129      * @return Whether or not it's the first character of a line
130      */
131     boolean isLineStart (int chpos);
132 
133     /**
134      * Get a line of text
135      *
136      * @param idx A line number
137      * @return The text
138      * @throws IOException If an error occurs and the text cannot be read
139      */
140     String   getLine (int idx) throws IOException  ;
141 
142     /**
143      * Determine if there are any hyperlinked lines (lines with associated output listeners)
144      * @return True if there are any listeners
145      */
146     boolean hasHyperlinks();
147 
148     /**
149      * Determine if this line has an associated OutputListener
150      * @param line A line number
151      * @return If it has a listener
152      */
153     boolean isHyperlink (int line);
154 
155     /**
156      * Count the total number of characters in the stored text
157      *
158      * @return The number of characters that have been written
159      */
160     int getCharCount();
161 
162     /**
163      * Fetch a getText of the entire text
164      * @param start A character position < end
165      * @param end A character position > start
166      * @return A String representation of the text between these points, including newlines
167      */
168     String   getText (int start, int end);
169 
170     /**
171      * Fetch a getText of the entire text into a character array
172      * @param start A character position < end
173      * @param end A character position >  start
174      * @param chars A character array at least as large as end-start, or null
175      * @return A character array containing the range of text specified
176      */
177     char[] getText (int start, int end, char[] chars);
178     /**
179       * Get a logical line index for a given point in the display space.
180       * This is to accomodate line wrapping using fixed width fonts - this
181       * method answers the question "What line of output does the nth row
182       * of lines correspond to, given <code>charsPerLine</code> characters
183       * per line?".  If the logical line in question is itself wrapped, it
184       * will also return how many wrapped lines down from the beginning of
185       * the logical line the passed row index is, and the total number of
186       * wraps for this logical line to fit inside <code>charsPerLine</code>.
187       *
188       * @param info A 3 entry array.  Element 0 should be the physical line
189       *        (the line position if no wrapping were happening) when called;
190       *        the other two elements are ignored.  On return,
191       *        it contains: <ul>
192       *         <li>[0] The logical line index for the passed line</li>
193       *         <li>[1] The number of line wraps below the logical line
194       *             index for this physical line</li>
195       *         <li>[2] The total number of line wraps for the logical line</li>
196       *         </ul>
197       */
198     void toLogicalLineIndex (int[] info, int charsPerLine);
199     /**
200      * Save the contents of the buffer to a file, in platform default encoding.
201      *
202      * @param path The file to save to
203      * @throws IOException If there is a problem writing or encoding the data, or if overwrite is false and the
204      *    specified file exists
205      */
206     void saveAs(String   path) throws IOException  ;
207 
208     /**
209      * Do a forward search for the last matched text (from a call to find()).
210      *
211      * @return A matcher, if there has been a successful call to find
212      */
213     Matcher   getForwardMatcher();
214     /**
215      * Do a reverse search for the last matched text.  Using this is a little tricky -
216      * since there is no direct support for reverse searches in java.util.regex, what
217      * we do is take the last pattern and the entire buffer text, and reverse them,
218      * and produce a matcher based on that.
219      * <p>
220      * What this means is that the caller gets the job of flipping things back around,
221      * as follows:
222      * <pre>
223      * int matchStart = getLength() - matcher.end();
224      * int matchEnd = getLength() - matcher.start()
225      *
226      * will return the actual positions in the data of the match.
227      *
228      * @return A matcher over a reversed version of the data
229      */
230     Matcher   getReverseMatcher();
231     /**
232      * Get a regular expression matcher over the backing storage.  Note that the resulting Matcher object
233      * should not be held across reset or other events that can destroy the contents of the buffer.
234      *
235      * @param s A pattern as defined in javax.regex
236      * @return A pattern matcher object, or null if the pattern is invalid or there is a problem with the
237      *   backing storage
238      */
239     Matcher   find(String   s);
240 
241     /**
242      * Indicates a line was written to the stderr, not stdout
243      *
244      * @param line A line number
245      * @return True if it was written to stderr
246      */
247     boolean isErr(int line);
248 
249     /**
250      * Acquire a read lock - while held, other threads cannot modify this Lines object.
251      *
252      * @return
253      */
254     Object   readLock();
255 
256     /**
257      * Add a change listener, which will detect when lines are written. <strong>Changes are
258      * <u>not</u> fired for every write; they should be fired when an initial line is written,
259      * when the writer is flushed, or when it is closed.</strong>  Clients which respond to ongoing
260      * writes should use a timer and poll via <code>checkDirty()</code> to see if new data has
261      * been written.
262      *
263      * @param cl A change listener
264      */
265     void addChangeListener (ChangeListener   cl);
266 
267     /**
268      * Remove a change listener.
269      *
270      * @param cl
271      */
272     void removeChangeListener (ChangeListener   cl);
273 
274     /**
275      * Allows clients that wish to poll to see if there is new output to do
276      * so.  When any thread writes to the output, the dirty flag is set.
277      * Calling this method returns its current value and clears it.  If it
278      * returns true, a view of the data may need to repaint itself or something
279      * such.  This mechanism can be used in preference to listener based
280      * notification, by running a timer to poll as long as the output is
281      * open, for cases where otherwise the event queue would be flooded with
282      * notifications for small writes.
283      *
284      * @param clear Whether or not to clear the dirty flag
285      */
286     boolean checkDirty(boolean clear);
287 
288     /**
289      * Determine whether or not the storage backing this Lines object is being actively written to.
290      * @return True if there is still an open stream which may write to the backing storage and no error has occured
291      */
292     boolean isGrowing();
293 }
294
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags