Source code: org/eclipse/jface/text/ITextViewer.java
1 /*******************************************************************************
2 * Copyright (c) 2000, 2004 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
7 *
8 * Contributors:
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11
12 package org.eclipse.jface.text;
13
14
15 import org.eclipse.swt.custom.StyledText;
16 import org.eclipse.swt.graphics.Color;
17 import org.eclipse.swt.graphics.Point;
18
19 import org.eclipse.jface.viewers.ISelectionProvider;
20
21
22 /**
23 * A text viewer connects a text widget with an
24 * {@link org.eclipse.jface.text.IDocument}. The document is used as the
25 * widget's text model.
26 * <p>
27 * It supports the following kinds of listeners:
28 * <ul>
29 * <li>view port listeners to inform about changes of the viewer's view port
30 * <li>text listeners to inform about changes of the document and the
31 * subsequent viewer change
32 * <li>text input listeners to inform about changes of the viewer's input
33 * document.
34 * </ul>
35 * A text viewer supports a set of configuration options and plug-ins defining
36 * its behavior:
37 * <ul>
38 * <li>undo manager
39 * <li>double click behavior
40 * <li>auto indentation
41 * <li>text hover
42 * </ul>
43 * Installed plug-ins are not automatically activated. Plug-ins must be
44 * activated with the <code>activatePlugins</code> call. Most plug-ins can be
45 * defined per content type. Content types are derived from a partitioning of
46 * the text viewer's input document. In case of documents that support multiple
47 * partitionings, the implementer is responsible for determining the
48 * partitioning to use.
49 * <p>
50 * A text viewer also provides the concept of event consumption. Events handled
51 * by the viewer can be filtered and processed by a dynamic event consumer. With
52 * {@link org.eclipse.jface.text.ITextViewerExtension}this mechanism has been
53 * replaced with the support for
54 * {@link org.eclipse.swt.custom.VerifyKeyListener}.
55 * <p>
56 * A text viewer provides several text editing functions, some of them are
57 * configurable, through a text operation target interface. It also supports a
58 * presentation mode in which it only shows a specified section of its document.
59 * By calling <code>setVisibleRegion</code> clients define which section is
60 * visible. Clients can get access to this section by calling
61 * <code>getVisibleRegion</code>. The viewer's presentation mode does not
62 * affect any client of the viewer other than text listeners. With
63 * {@link org.eclipse.jface.text.ITextViewerExtension5}the visible region
64 * support has been reworked. With that extension interface, text viewers are
65 * allowed to show fractions of their input document. I.e. a widget selection of
66 * two visually neighboring characters is no longer guaranteed to be two
67 * neighboring characters in the viewer's input document. Thus, viewers
68 * implementing {@link org.eclipse.jface.text.ITextViewerExtension5}are
69 * potentially forced to change the fractions of the input document that are
70 * shown when clients ask for the visible region.
71 * <p>
72 *
73 * In order to provide backward compatibility for clients of
74 * <code>ITextViewer</code>, extension interfaces are used as a means of
75 * evolution. The following extension interfaces exist:
76 * <ul>
77 * <li>{@link org.eclipse.jface.text.ITextViewerExtension}since version 2.0
78 * replacing the event consumer mechanism and introducing the concept of rewrite
79 * targets and means to manage the viewer's redraw behavior</li>
80 * <li>{@link org.eclipse.jface.text.ITextViewerExtension2}since version 2.1
81 * adding a way to invalidate a viewer's presentation and setters for hovers.
82 * </li>
83 * <li>{@link org.eclipse.jface.text.ITextViewerExtension3}since version 2.1
84 * which itself was replaced by
85 * {@link org.eclipse.jface.text.ITextViewerExtension5}in version 3.0</li>
86 * <li>{@link org.eclipse.jface.text.ITextViewerExtension4}since version 3.0
87 * introducing focus handling for widget token keepers and the concept of text
88 * presentation listeners.</li>
89 * <li>{@link org.eclipse.jface.text.ITextViewerExtension5}since version 3.0
90 * extending the visible region concept with explicit handling and conversation
91 * of widget and model coordinates.</li>
92 * </ul>
93 *
94 * Clients may implement this interface and its extension interfaces or use the
95 * standard implementation {@link org.eclipse.jface.text.TextViewer}.
96 *
97 * @see org.eclipse.jface.text.ITextViewerExtension
98 * @see org.eclipse.jface.text.ITextViewerExtension2
99 * @see org.eclipse.jface.text.ITextViewerExtension3
100 * @see org.eclipse.jface.text.ITextViewerExtension4
101 * @see org.eclipse.jface.text.ITextViewerExtension5
102 * @see org.eclipse.jface.text.IDocument
103 * @see org.eclipse.jface.text.ITextInputListener
104 * @see org.eclipse.jface.text.IViewportListener
105 * @see org.eclipse.jface.text.ITextListener
106 * @see org.eclipse.jface.text.IEventConsumer
107 */
108 public interface ITextViewer {
109
110
111 /* ---------- widget --------- */
112
113 /**
114 * Returns this viewer's SWT control, <code>null</code> if the control is disposed.
115 *
116 * @return the SWT control or <code>null</code>
117 */
118 StyledText getTextWidget();
119
120
121 /* --------- plug-ins --------- */
122
123 /**
124 * Sets this viewer's undo manager.
125 *
126 * @param undoManager the new undo manager. <code>null</code> is a valid argument.
127 */
128 void setUndoManager(IUndoManager undoManager);
129
130 /**
131 * Sets this viewer's text double click strategy for the given content type.
132 *
133 * @param strategy the new double click strategy. <code>null</code> is a valid argument.
134 * @param contentType the type for which the strategy is registered
135 */
136 void setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy, String contentType);
137
138 /**
139 * Sets this viewer's auto indent strategy for the given content type. If
140 * the given strategy is <code>null</code> any installed strategy for the
141 * content type is removed. This method has been replaced by
142 * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)}
143 * and
144 * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)}.
145 * It is now equivalent to
146 * <pre>
147 * ITextViewerExtension2 extension= (ITextViewerExtension2) viewer;
148 * extension.removeAutoEditStrategy(oldStrategy, contentType);
149 * extension.prependAutoEditStrategy(strategy, contentType);
150 * </pre>
151 *
152 * @param strategy the new auto indent strategy. <code>null</code> is a
153 * valid argument.
154 * @param contentType the type for which the strategy is registered
155 */
156 void setAutoIndentStrategy(IAutoIndentStrategy strategy, String contentType);
157
158 /**
159 * Sets this viewer's text hover for the given content type.
160 * <p>
161 * This method has been replaced by {@link ITextViewerExtension2#setTextHover(ITextHover, String, int)}.
162 * It is now equivalent to
163 * <pre>
164 * ITextViewerExtension2 extension= (ITextViewerExtension2) document;
165 * extension.setTextHover(textViewerHover, contentType, ITextViewerExtension2#DEFAULT_HOVER_STATE_MASK);
166 * </pre>
167 *
168 *
169 * @param textViewerHover the new hover. <code>null</code> is a valid
170 * argument.
171 * @param contentType the type for which the hover is registered
172 */
173 void setTextHover(ITextHover textViewerHover, String contentType);
174
175 /**
176 * Activates the installed plug-ins. If the plug-ins are already activated
177 * this call has no effect.
178 */
179 void activatePlugins();
180
181 /**
182 * Resets the installed plug-ins. If plug-ins change their state or
183 * behavior over the course of time, this method causes them to be set
184 * back to their initial state and behavior. E.g., if an {@link IUndoManager}
185 * has been installed on this text viewer, the manager's list of remembered
186 * text editing operations is removed.
187 */
188 void resetPlugins();
189
190
191
192 /* ---------- listeners ------------- */
193
194 /**
195 * Adds the given view port listener to this viewer. The listener
196 * is informed about all changes to the visible area of this viewer.
197 * If the listener is already registered with this viewer, this call
198 * has no effect.
199 *
200 * @param listener the listener to be added
201 */
202 void addViewportListener(IViewportListener listener);
203
204 /**
205 * Removes the given listener from this viewer's set of view port listeners.
206 * If the listener is not registered with this viewer, this call has
207 * no effect.
208 *
209 * @param listener the listener to be removed
210 */
211 void removeViewportListener(IViewportListener listener);
212
213 /**
214 * Adds a text listener to this viewer. If the listener is already registered
215 * with this viewer, this call has no effect.
216 *
217 * @param listener the listener to be added
218 */
219 void addTextListener(ITextListener listener);
220
221 /**
222 * Removes the given listener from this viewer's set of text listeners.
223 * If the listener is not registered with this viewer, this call has
224 * no effect.
225 *
226 * @param listener the listener to be removed
227 */
228 void removeTextListener(ITextListener listener);
229
230 /**
231 * Adds a text input listener to this viewer. If the listener is already registered
232 * with this viewer, this call has no effect.
233 *
234 * @param listener the listener to be added
235 */
236 void addTextInputListener(ITextInputListener listener);
237
238 /**
239 * Removes the given listener from this viewer's set of text input listeners.
240 * If the listener is not registered with this viewer, this call has
241 * no effect.
242 *
243 * @param listener the listener to be removed
244 */
245 void removeTextInputListener(ITextInputListener listener);
246
247
248
249 /* -------------- model manipulation ------------- */
250
251 /**
252 * Sets the given document as the text viewer's model and updates the
253 * presentation accordingly. An appropriate <code>TextEvent</code> is
254 * issued. This text event does not carry a related document event.
255 *
256 * @param document the viewer's new input document
257 */
258 void setDocument(IDocument document);
259
260 /**
261 * Returns the text viewer's input document.
262 *
263 * @return the viewer's input document
264 */
265 IDocument getDocument();
266
267
268 /* -------------- event handling ----------------- */
269
270 /**
271 * Registers an event consumer with this viewer. This method has been
272 * replaces with the {@link org.eclipse.swt.custom.VerifyKeyListener}
273 * management methods in {@link ITextViewerExtension}.
274 *
275 * @param consumer the viewer's event consumer. <code>null</code> is a
276 * valid argument.
277 */
278 void setEventConsumer(IEventConsumer consumer);
279
280 /**
281 * Sets the editable state.
282 *
283 * @param editable the editable state
284 */
285 void setEditable(boolean editable);
286
287 /**
288 * Returns whether the shown text can be manipulated.
289 *
290 * @return the viewer's editable state
291 */
292 boolean isEditable();
293
294
295 /* ----------- visible region support ------------- */
296
297 /**
298 * Sets the given document as this viewer's model and
299 * exposes the specified region. An appropriate
300 * <code>TextEvent</code> is issued. The text event does not carry a
301 * related document event. This method is a convenience method for
302 * <code>setDocument(document);setVisibleRegion(offset, length)</code>.
303 *
304 * @param document the new input document
305 * @param modelRangeOffset the offset of the model range
306 * @param modelRangeLength the length of the model range
307 */
308 void setDocument(IDocument document, int modelRangeOffset, int modelRangeLength);
309
310 /**
311 * Defines and sets the region of this viewer's document which will be
312 * visible in the presentation. Every character inside the specified region
313 * is supposed to be visible in the viewer's widget after that call.
314 *
315 * @param offset the offset of the visible region
316 * @param length the length of the visible region
317 */
318 void setVisibleRegion(int offset, int length);
319
320 /**
321 * Resets the region of this viewer's document which is visible in the presentation.
322 * Afterwards, the whole input document is visible.
323 */
324 void resetVisibleRegion();
325
326 /**
327 * Returns the current visible region of this viewer's document. The result
328 * may differ from the argument passed to <code>setVisibleRegion</code> if
329 * the document has been modified since then. The visible region is supposed
330 * to be a consecutive region in viewer's input document and every character
331 * inside that region is supposed to visible in the viewer's widget.
332 * <p>
333 * Viewers implementing {@link ITextViewerExtension5} may be forced to
334 * change the fractions of the input document that are shown, in order to
335 * fulfill this contract.
336 *
337 * @return this viewer's current visible region
338 */
339 IRegion getVisibleRegion();
340
341 /**
342 * Returns whether a given range overlaps with the visible region of this
343 * viewer's document.
344 * <p>
345 * Viewers implementing {@link ITextViewerExtension5}may be forced to
346 * change the fractions of the input document that are shown in order to
347 * fulfill this request. This is because the overlap is supposed to be
348 * without gaps.
349 *
350 * @param offset the offset
351 * @param length the length
352 * @return <code>true</code> if the specified range overlaps with the
353 * visible region
354 */
355 boolean overlapsWithVisibleRegion(int offset, int length);
356
357
358
359 /* ------------- presentation manipulation ----------- */
360
361 /**
362 * Applies the color information encoded in the given text presentation.
363 * <code>controlRedraw</code> tells this viewer whether it should take care of
364 * redraw management or not. If, e.g., this call is one in a sequence of multiple
365 * presentation calls, it is more appropriate to explicitly control redrawing at the
366 * beginning and the end of the sequence.
367 *
368 * @param presentation the presentation to be applied to this viewer
369 * @param controlRedraw indicates whether this viewer should manage redraws
370 */
371 void changeTextPresentation(TextPresentation presentation, boolean controlRedraw);
372
373 /**
374 * Marks the currently applied text presentation as invalid. It is the
375 * viewer's responsibility to take any action it can to repair the text
376 * presentation.
377 * <p>
378 * See {@link ITextViewerExtension2#invalidateTextPresentation(int, int)}
379 * for a way to invalidate specific regions rather than the presentation as
380 * a whole.
381 *
382 * @since 2.0
383 */
384 void invalidateTextPresentation();
385
386 /**
387 * Applies the given color as text foreground color to this viewer's
388 * selection.
389 *
390 * @param color the color to be applied
391 */
392 void setTextColor(Color color);
393
394 /**
395 * Applies the given color as text foreground color to the specified section
396 * of this viewer. <code>controlRedraw</code> tells this viewer whether it
397 * should take care of redraw management or not.
398 *
399 * @param color the color to be applied
400 * @param offset the offset of the range to be changed
401 * @param length the length of the range to be changed
402 * @param controlRedraw indicates whether this viewer should manage redraws
403 */
404 void setTextColor(Color color, int offset, int length, boolean controlRedraw);
405
406
407 /* --------- target handling and configuration ------------ */
408
409 /**
410 * Returns the text operation target of this viewer.
411 *
412 * @return the text operation target of this viewer
413 */
414 ITextOperationTarget getTextOperationTarget();
415
416 /**
417 * Returns the find/replace operation target of this viewer.
418 *
419 * @return the find/replace operation target of this viewer
420 */
421 IFindReplaceTarget getFindReplaceTarget();
422
423 /**
424 * Sets the string that is used as prefix when lines of the given
425 * content type are prefixed by the prefix text operation.
426 * Sets the strings that are used as prefixes when lines of the given content type
427 * are prefixed using the prefix text operation. The prefixes are considered equivalent.
428 * Inserting a prefix always inserts the defaultPrefixes[0].
429 * Removing a prefix removes all of the specified prefixes.
430 *
431 * @param defaultPrefixes the prefixes to be used
432 * @param contentType the content type for which the prefixes are specified
433 * @since 2.0
434 */
435 void setDefaultPrefixes(String[] defaultPrefixes, String contentType);
436
437 /**
438 * Sets the strings that are used as prefixes when lines of the given content type
439 * are shifted using the shift text operation. The prefixes are considered equivalent.
440 * Thus "\t" and " " can both be used as prefix characters.
441 * Shift right always inserts the indentPrefixes[0].
442 * Shift left removes all of the specified prefixes.
443 *
444 * @param indentPrefixes the prefixes to be used
445 * @param contentType the content type for which the prefixes are specified
446 */
447 void setIndentPrefixes(String[] indentPrefixes, String contentType);
448
449
450
451 /* --------- selection handling -------------- */
452
453 /**
454 * Sets the selection to the specified range.
455 *
456 * @param offset the offset of the selection range
457 * @param length the length of the selection range
458 */
459 void setSelectedRange(int offset, int length);
460
461 /**
462 * Returns the range of the current selection in coordinates of this viewer's document.
463 *
464 * @return the current selection
465 */
466 Point getSelectedRange();
467
468 /**
469 * Returns a selection provider dedicated to this viewer. Subsequent
470 * calls to this method return always the same selection provider.
471 *
472 * @return this viewer's selection provider
473 */
474 ISelectionProvider getSelectionProvider();
475
476
477 /* ------------- appearance manipulation --------------- */
478
479 /**
480 * Ensures that the given range is visible.
481 *
482 * @param offset the offset of the range to be revealed
483 * @param length the length of the range to be revealed
484 */
485 void revealRange(int offset, int length);
486
487 /**
488 * Scrolls the widget so the the given index is the line
489 * with the smallest line number of all visible lines.
490 *
491 * @param index the line which should become the top most line
492 */
493 void setTopIndex(int index);
494
495 /**
496 * Returns the visible line with the smallest line number.
497 *
498 * @return the number of the top most visible line
499 */
500 int getTopIndex();
501
502 /**
503 * Returns the document offset of the upper left corner of this viewer's view port.
504 *
505 * @return the upper left corner offset
506 */
507 int getTopIndexStartOffset();
508
509 /**
510 * Returns the visible line with the highest line number.
511 *
512 * @return the number of the bottom most line
513 */
514 int getBottomIndex();
515
516 /**
517 * Returns the document offset of the lower right
518 * corner of this viewer's view port. This is the visible character
519 * with the highest character position. If the content of this viewer
520 * is shorter, the position of the last character of the content is returned.
521 *
522 * @return the lower right corner offset
523 */
524 int getBottomIndexEndOffset();
525
526 /**
527 * Returns the vertical offset of the first visible line.
528 *
529 * @return the vertical offset of the first visible line
530 */
531 int getTopInset();
532 }