01: /*******************************************************************************
02: * Copyright (c) 2000, 2005 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.jface.text;
11:
12: import org.eclipse.jface.viewers.ISelection;
13:
14: /**
15: * This interface represents a textual selection. A text selection is a range of
16: * characters. Although a text selection is a snapshot taken at a particular
17: * point in time, it must not copy the line information and the selected text
18: * from the selection provider.
19: * <p>
20: * If, for example, the selection provider is a text viewer (
21: * {@link org.eclipse.jface.text.ITextViewer}), and a text selection is created
22: * for the range [5, 10], the line formation for the 5th character must not be
23: * determined and remembered at the point of creation. It can rather be
24: * determined at the point, when <code>getStartLine</code> is called. If the
25: * source viewer range [0, 15] has been changed in the meantime between the
26: * creation of the text selection object and the invocation of
27: * <code>getStartLine</code>, the returned line number may differ from the
28: * line number of the 5th character at the point of creation of the text
29: * selection object.
30: * <p>
31: * The contract of this interface is that weak in order to allow for efficient
32: * implementations.</p>
33: * <p>
34: * Clients may implement this interface or use the default implementation
35: * provided by {@link org.eclipse.jface.text.TextSelection}.</p>
36: *
37: * @see org.eclipse.jface.text.TextSelection
38: */
39: public interface ITextSelection extends ISelection {
40:
41: /**
42: * Returns the offset of the selected text.
43: *
44: * @return the offset of the selected text
45: */
46: int getOffset();
47:
48: /**
49: * Returns the length of the selected text.
50: *
51: * @return the length of the selected text
52: */
53: int getLength();
54:
55: /**
56: * Returns number of the line containing the offset of the selected text.
57: * If the underlying text has been changed between the creation of this
58: * selection object and the call of this method, the value returned might
59: * differ from what it would have been at the point of creation.
60: *
61: * @return the start line of this selection or <code>-1</code> if there is no valid line information
62: */
63: int getStartLine();
64:
65: /**
66: * Returns the number of the line containing the last character of the selected text.
67: * If the underlying text has been changed between the creation of this
68: * selection object and the call of this method, the value returned might
69: * differ from what it would have been at the point of creation.
70: *
71: * @return the end line of this selection or <code>-1</code> if there is no valid line information
72: */
73: int getEndLine();
74:
75: /**
76: * Returns the selected text.
77: * If the underlying text has been changed between the creation of this
78: * selection object and the call of this method, the value returned might
79: * differ from what it would have been at the point of creation.
80: *
81: * @return the selected text or <code>null</code> if there is no valid text information
82: */
83: String getText();
84: }
|