ILineTracker


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.text;
12  
13  
14  /**
15   * A line tracker maps character positions to line numbers and vice versa.
16   * Initially the line tracker is informed about its underlying text in order to
17   * initialize the mapping information. After that, the line tracker is informed
18   * about all changes of the underlying text allowing for incremental updates of
19   * the mapping information. It is the client's responsibility to actively inform
20   * the line tacker about text changes. For example, when using a line tracker in
21   * combination with a document the document controls the line tracker.
22   * <p>
23   * In order to provide backward compatibility for clients of <code>ILineTracker</code>, extension
24   * interfaces are used to provide a means of evolution. The following extension interfaces
25   * exist:
26   * <ul>
27   * <li> {@link org.eclipse.jface.text.ILineTrackerExtension} since version 3.1 introducing the concept
28   *      of rewrite sessions.</li>
29   * </ul>
30   * <p>
31   * Clients may implement this interface or use the standard implementation
32   * </p>
33   * {@link org.eclipse.jface.text.DefaultLineTracker}or
34   * {@link org.eclipse.jface.text.ConfigurableLineTracker}.
35   */
36  public interface ILineTracker {
37  
38      /**
39       * Returns the strings this tracker considers as legal line delimiters.
40       *
41       * @return the legal line delimiters
42       */
43      String  [] getLegalLineDelimiters();
44  
45      /**
46       * Returns the line delimiter of the specified line. Returns <code>null</code> if the
47       * line is not closed with a line delimiter.
48       *
49       * @param line the line whose line delimiter is queried
50       * @return the line's delimiter or <code>null</code> if line does not have a delimiter
51       * @exception BadLocationException if the line number is invalid in this tracker's line structure
52       */
53      String   getLineDelimiter(int line) throws BadLocationException;
54  
55      /**
56       * Computes the number of lines in the given text.
57       *
58       * @param text the text whose number of lines should be computed
59       * @return the number of lines in the given text
60       */
61      int computeNumberOfLines(String   text);
62  
63      /**
64       * Returns the number of lines.
65       *
66       * @return the number of lines in this tracker's line structure
67       */
68      int getNumberOfLines();
69  
70      /**
71       * Returns the number of lines which are occupied by a given text range.
72       *
73       * @param offset the offset of the specified text range
74       * @param length the length of the specified text range
75       * @return the number of lines occupied by the specified range
76       * @exception BadLocationException if specified range is unknown to this tracker
77       */
78      int getNumberOfLines(int offset, int length) throws BadLocationException;
79  
80      /**
81       * Returns the position of the first character of the specified line.
82       *
83       * @param line the line of interest
84       * @return offset of the first character of the line
85       * @exception BadLocationException if the line is unknown to this tracker
86       */
87      int getLineOffset(int line) throws BadLocationException;
88  
89      /**
90       * Returns length of the specified line including the line's delimiter.
91       *
92       * @param line the line of interest
93       * @return the length of the line
94       * @exception BadLocationException if line is unknown to this tracker
95       */
96      int getLineLength(int line) throws BadLocationException;
97  
98      /**
99       * Returns the line number the character at the given offset belongs to.
100      *
101      * @param offset the offset whose line number to be determined
102      * @return the number of the line the offset is on
103      * @exception BadLocationException if the offset is invalid in this tracker
104      */
105     int getLineNumberOfOffset(int offset) throws BadLocationException;
106 
107     /**
108      * Returns a line description of the line at the given offset.
109      * The description contains the start offset and the length of the line
110      * excluding the line's delimiter.
111      *
112      * @param offset the offset whose line should be described
113      * @return a region describing the line
114      * @exception BadLocationException if offset is invalid in this tracker
115      */
116     IRegion getLineInformationOfOffset(int offset) throws BadLocationException;
117 
118     /**
119      * Returns a line description of the given line. The description
120      * contains the start offset and the length of the line excluding the line's
121      * delimiter.
122      *
123      * @param line the line that should be described
124      * @return a region describing the line
125      * @exception BadLocationException if line is unknown to this tracker
126      */
127     IRegion getLineInformation(int line) throws BadLocationException;
128 
129     /**
130      * Informs the line tracker about the specified change in the tracked text.
131      *
132      * @param offset the offset of the replaced text
133      * @param length the length of the replaced text
134      * @param text the substitution text
135      * @exception BadLocationException if specified range is unknown to this tracker
136      */
137     void replace(int offset, int length, String   text) throws BadLocationException;
138 
139     /**
140      * Sets the tracked text to the specified text.
141      *
142      * @param text the new tracked text
143      */
144     void set(String   text);
145 }
146
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags