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 import org.eclipse.jface.viewers.ISelection; 16 17 18 /** 19 * This interface represents a textual selection. A text selection is a range of 20 * characters. Although a text selection is a snapshot taken at a particular 21 * point in time, it must not copy the line information and the selected text 22 * from the selection provider. 23 * <p> 24 * If, for example, the selection provider is a text viewer ( 25 * {@link org.eclipse.jface.text.ITextViewer}), and a text selection is created 26 * for the range [5, 10], the line formation for the 5th character must not be 27 * determined and remembered at the point of creation. It can rather be 28 * determined at the point, when <code>getStartLine</code> is called. If the 29 * source viewer range [0, 15] has been changed in the meantime between the 30 * creation of the text selection object and the invocation of 31 * <code>getStartLine</code>, the returned line number may differ from the 32 * line number of the 5th character at the point of creation of the text 33 * selection object. 34 * <p> 35 * The contract of this interface is that weak in order to allow for efficient 36 * implementations.</p> 37 * <p> 38 * Clients may implement this interface or use the default implementation 39 * provided by {@link org.eclipse.jface.text.TextSelection}.</p> 40 * 41 * @see org.eclipse.jface.text.TextSelection 42 */ 43 public interface ITextSelection extends ISelection { 44 45 /** 46 * Returns the offset of the selected text. 47 * 48 * @return the offset of the selected text 49 */ 50 int getOffset(); 51 52 /** 53 * Returns the length of the selected text. 54 * 55 * @return the length of the selected text 56 */ 57 int getLength(); 58 59 /** 60 * Returns number of the line containing the offset of the selected text. 61 * If the underlying text has been changed between the creation of this 62 * selection object and the call of this method, the value returned might 63 * differ from what it would have been at the point of creation. 64 * 65 * @return the start line of this selection or <code>-1</code> if there is no valid line information 66 */ 67 int getStartLine(); 68 69 /** 70 * Returns the number of the line containing the last character of the selected text. 71 * If the underlying text has been changed between the creation of this 72 * selection object and the call of this method, the value returned might 73 * differ from what it would have been at the point of creation. 74 * 75 * @return the end line of this selection or <code>-1</code> if there is no valid line information 76 */ 77 int getEndLine(); 78 79 /** 80 * Returns the selected text. 81 * If the underlying text has been changed between the creation of this 82 * selection object and the call of this method, the value returned might 83 * differ from what it would have been at the point of creation. 84 * 85 * @return the selected text or <code>null</code> if there is no valid text information 86 */ 87 String getText(); 88 } 89 90