1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
/*******************************************************************************
* Copyright (c) 2000, 2010 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui.texteditor;
import org.eclipse.jface.action.IAction;
import org.eclipse.jface.viewers.ISelectionProvider;
import org.eclipse.jface.text.IRegion;
import org.eclipse.ui.IEditorPart;
/**
* Interface to a text editor. This interface defines functional extensions to
* <code>IEditorPart</code> as well as the configuration capabilities of a text editor.
* <p>
* Text editors are configured with an <code>IDocumentProvider</code> which delivers a textual
* presentation (<code>IDocument</code>) of the editor's input. The editor works on the document and
* forwards all input element related calls, such as <code>save</code>, to the document provider.
* The provider also delivers the input's annotation model which is used by the editor's vertical
* ruler.
* </p>
* <p>
* Clients may implement this interface from scratch, but the recommended way is to subclass the
* abstract base class <code>AbstractTextEditor</code>.
* </p>
* <p>
* In order to provided backward compatibility for clients of <code>ITextEditor</code>, extension
* interfaces are used to provide a means of evolution. The following extension interfaces exist:
* <ul>
* <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension} since version 2.0 introducing status
* fields, read-only state and ruler context menu listeners.</li>
* <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension2} since version 2.1 introducing
* modifiable state for the editor input and validate state handling.</li>
* <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension3} since version 3.0 adding input state
* and change information control.</li>
* <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension4} since version 3.2 adding annotation
* navigation and revision information display.</li>
* <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension5} since version 3.5 adding block
* selection mode.</li>
* </ul>
* </p>
*
* @see org.eclipse.ui.texteditor.IDocumentProvider
* @see org.eclipse.jface.text.source.IAnnotationModel
* @see org.eclipse.ui.texteditor.ITextEditorExtension
* @see org.eclipse.ui.texteditor.ITextEditorExtension2
* @see org.eclipse.ui.texteditor.ITextEditorExtension3
* @see org.eclipse.ui.texteditor.ITextEditorExtension4
* @see org.eclipse.ui.texteditor.ITextEditorExtension5
*/
public interface ITextEditor extends IEditorPart {
/**
* Returns this text editor's document provider.
*
* @return the document provider or <code>null</code> if none, e.g. after closing the editor
*/
IDocumentProvider getDocumentProvider();
/**
* Closes this text editor after optionally saving changes.
*
* @param save <code>true</code> if unsaved changed should be saved, and
* <code>false</code> if unsaved changed should be discarded
*/
void close(boolean save);
/**
* Returns whether the text in this text editor can be changed by the user.
*
* @return <code>true</code> if it can be edited, and <code>false</code> if it is read-only
*/
boolean isEditable();
/**
* Abandons all modifications applied to this text editor's input element's
* textual presentation since the last save operation.
*/
void doRevertToSaved();
/**
* Installs the given action under the given action id.
*
* @param actionID the action id
* @param action the action, or <code>null</code> to clear it
* @see #getAction(String)
*/
void setAction(String actionID, IAction action);
/**
* Returns the action installed under the given action id.
*
* @param actionId the action id
* @return the action, or <code>null</code> if none
* @see #setAction(String, IAction)
*/
IAction getAction(String actionId);
/**
* Sets the given activation code for the specified action. If
* there is an activation code already registered, it is replaced.
* The activation code consists of the same information as
* a <code>KeyEvent</code>. If the activation code is triggered
* and the associated action is enabled, the action is performed
* and the triggering <code>KeyEvent</code> is considered consumed.
* If the action is disabled, the <code>KeyEvent</code> is passed
* on unmodified. Thus, action activation codes and action accelerators
* differ in their model of event consumption. The key code parameter
* can be <code>-1</code> to indicate a wild card. The state mask
* parameter can be SWT.DEFAULT to indicate a wild card.
*
* @param actionId the action id
* @param activationCharacter the activation code character
* @param activationKeyCode the activation code key code or <code>-1</code> for wild card
* @param activationStateMask the activation code state mask or <code>SWT.DEFAULT</code> for wild card
*/
void setActionActivationCode(String actionId, char activationCharacter, int activationKeyCode, int activationStateMask);
/**
* Removes any installed activation code for the specified action.
* If no activation code is installed, this method does not have
* any effect.
*
* @param actionId the action id
*/
void removeActionActivationCode(String actionId);
/**
* Returns whether this text editor is configured to show only the
* highlighted range of the text.
*
* @return <code>true</code> if only the highlighted range is shown, and
* <code>false</code> if this editor shows the entire text of the document
* @see #showHighlightRangeOnly(boolean)
*/
boolean showsHighlightRangeOnly();
/**
* Configures this text editor to show only the highlighted range of the
* text.
*
* @param showHighlightRangeOnly <code>true</code> if only the highlighted
* range is shown, and <code>false</code> if this editor shows the entire
* text of the document
* @see #showsHighlightRangeOnly()
*/
void showHighlightRangeOnly(boolean showHighlightRangeOnly);
/**
* Sets the highlighted range of this text editor to the specified region.
*
* @param offset the offset of the highlighted range
* @param length the length of the highlighted range
* @param moveCursor <code>true</code> if the cursor should be moved to the start of the
* highlighted range, and <code>false</code> to leave the cursor unaffected - has no
* effect if the range to highlight is already the highlighted one
* @see #getHighlightRange()
*/
void setHighlightRange(int offset, int length, boolean moveCursor);
/**
* Returns the highlighted range of this text editor.
*
* @return the highlighted range
* @see #setHighlightRange(int, int, boolean)
*/
IRegion getHighlightRange();
/**
* Resets the highlighted range of this text editor.
*/
void resetHighlightRange();
/**
* Returns this text editor's selection provider. Repeated calls to this
* method return the same selection provider.
*
* @return the selection provider
*/
ISelectionProvider getSelectionProvider();
/**
* Selects and reveals the specified range in this text editor.
*
* @param offset the offset of the selection
* @param length the length of the selection
*/
void selectAndReveal(int offset, int length);
}
|
