001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text;
011:
012: /**
013: * A line tracker maps character positions to line numbers and vice versa.
014: * Initially the line tracker is informed about its underlying text in order to
015: * initialize the mapping information. After that, the line tracker is informed
016: * about all changes of the underlying text allowing for incremental updates of
017: * the mapping information. It is the client's responsibility to actively inform
018: * the line tacker about text changes. For example, when using a line tracker in
019: * combination with a document the document controls the line tracker.
020: * <p>
021: * In order to provide backward compatibility for clients of <code>ILineTracker</code>, extension
022: * interfaces are used to provide a means of evolution. The following extension interfaces
023: * exist:
024: * <ul>
025: * <li> {@link org.eclipse.jface.text.ILineTrackerExtension} since version 3.1 introducing the concept
026: * of rewrite sessions.</li>
027: * </ul>
028: * <p>
029: * Clients may implement this interface or use the standard implementation
030: * </p>
031: * {@link org.eclipse.jface.text.DefaultLineTracker}or
032: * {@link org.eclipse.jface.text.ConfigurableLineTracker}.
033: */
034: public interface ILineTracker {
035:
036: /**
037: * Returns the strings this tracker considers as legal line delimiters.
038: *
039: * @return the legal line delimiters
040: */
041: String[] getLegalLineDelimiters();
042:
043: /**
044: * Returns the line delimiter of the specified line. Returns <code>null</code> if the
045: * line is not closed with a line delimiter.
046: *
047: * @param line the line whose line delimiter is queried
048: * @return the line's delimiter or <code>null</code> if line does not have a delimiter
049: * @exception BadLocationException if the line number is invalid in this tracker's line structure
050: */
051: String getLineDelimiter(int line) throws BadLocationException;
052:
053: /**
054: * Computes the number of lines in the given text.
055: *
056: * @param text the text whose number of lines should be computed
057: * @return the number of lines in the given text
058: */
059: int computeNumberOfLines(String text);
060:
061: /**
062: * Returns the number of lines.
063: *
064: * @return the number of lines in this tracker's line structure
065: */
066: int getNumberOfLines();
067:
068: /**
069: * Returns the number of lines which are occupied by a given text range.
070: *
071: * @param offset the offset of the specified text range
072: * @param length the length of the specified text range
073: * @return the number of lines occupied by the specified range
074: * @exception BadLocationException if specified range is unknown to this tracker
075: */
076: int getNumberOfLines(int offset, int length)
077: throws BadLocationException;
078:
079: /**
080: * Returns the position of the first character of the specified line.
081: *
082: * @param line the line of interest
083: * @return offset of the first character of the line
084: * @exception BadLocationException if the line is unknown to this tracker
085: */
086: int getLineOffset(int line) throws BadLocationException;
087:
088: /**
089: * Returns length of the specified line including the line's delimiter.
090: *
091: * @param line the line of interest
092: * @return the length of the line
093: * @exception BadLocationException if line is unknown to this tracker
094: */
095: int getLineLength(int line) throws BadLocationException;
096:
097: /**
098: * Returns the line number the character at the given offset belongs to.
099: *
100: * @param offset the offset whose line number to be determined
101: * @return the number of the line the offset is on
102: * @exception BadLocationException if the offset is invalid in this tracker
103: */
104: int getLineNumberOfOffset(int offset) throws BadLocationException;
105:
106: /**
107: * Returns a line description of the line at the given offset.
108: * The description contains the start offset and the length of the line
109: * excluding the line's delimiter.
110: *
111: * @param offset the offset whose line should be described
112: * @return a region describing the line
113: * @exception BadLocationException if offset is invalid in this tracker
114: */
115: IRegion getLineInformationOfOffset(int offset)
116: 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)
138: throws BadLocationException;
139:
140: /**
141: * Sets the tracked text to the specified text.
142: *
143: * @param text the new tracked text
144: */
145: void set(String text);
146: }
|