Skip to main content
summaryrefslogtreecommitdiffstats
blob: b9547312a6ba136e894012797461e7ea0e195eb9 (plain) (blame)
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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
/*******************************************************************************
 * Copyright (c) 2000, 2009 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.text;

import org.eclipse.swt.custom.StyledText;
import org.eclipse.swt.graphics.Color;
import org.eclipse.swt.graphics.Point;

import org.eclipse.jface.viewers.ISelectionProvider;


/**
 * A text viewer connects a text widget with an
 * {@link org.eclipse.jface.text.IDocument}. The document is used as the
 * widget's text model.
 * <p>
 * It supports the following kinds of listeners:
 * <ul>
 * <li>view port listeners to inform about changes of the viewer's view port</li>
 * <li>text listeners to inform about changes of the document and the
 * subsequent viewer change</li>
 * <li>text input listeners to inform about changes of the viewer's input
 * document.</li>
 * </ul>
 * A text viewer supports a set of configuration options and plug-ins defining
 * its behavior:
 * <ul>
 * <li>undo manager</li>
 * <li>double click behavior</li>
 * <li>auto indentation</li>
 * <li>text hover</li>
 * </ul>
 * Installed plug-ins are not automatically activated. Plug-ins must be
 * activated with the <code>activatePlugins</code> call. Most plug-ins can be
 * defined per content type. Content types are derived from a partitioning of
 * the text viewer's input document. In case of documents that support multiple
 * partitionings, the implementer is responsible for determining the
 * partitioning to use.
 * <p>
 * A text viewer also provides the concept of event consumption. Events handled
 * by the viewer can be filtered and processed by a dynamic event consumer. With
 * {@link org.eclipse.jface.text.ITextViewerExtension}, this mechanism has been
 * replaced with the support for
 * {@link org.eclipse.swt.custom.VerifyKeyListener}.
 * <p>
 * A text viewer provides several text editing functions, some of them are
 * configurable, through a text operation target interface. It also supports a
 * presentation mode in which it only shows a specified section of its document.
 * By calling <code>setVisibleRegion</code> clients define which section is
 * visible. Clients can get access to this section by calling
 * <code>getVisibleRegion</code>. The viewer's presentation mode does not
 * affect any client of the viewer other than text listeners. With
 * {@link org.eclipse.jface.text.ITextViewerExtension5} the visible region
 * support has been reworked. With that extension interface, text viewers are
 * allowed to show fractions of their input document. I.e. a widget selection of
 * two visually neighboring characters is no longer guaranteed to be two
 * neighboring characters in the viewer's input document. Thus, viewers
 * implementing {@link org.eclipse.jface.text.ITextViewerExtension5} are
 * potentially forced to change the fractions of the input document that are
 * shown when clients ask for the visible region.
 * <p>
 *
 * In order to provide backward compatibility for clients of
 * <code>ITextViewer</code>, extension interfaces are used as a means of
 * evolution. The following extension interfaces exist:
 * <ul>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension} since version 2.0
 * replacing the event consumer mechanism and introducing the concept of rewrite
 * targets and means to manage the viewer's redraw behavior</li>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension2}since version 2.1
 * adding a way to invalidate a viewer's presentation and setters for hovers.
 * </li>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension3} since version 2.1
 * which itself was replaced by
 * {@link org.eclipse.jface.text.ITextViewerExtension5} in version 3.0</li>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension4} since version 3.0
 * introducing focus handling for widget token keepers and the concept of text
 * presentation listeners.</li>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension5} since version 3.0
 * extending the visible region concept with explicit handling and conversion
 * of widget and model coordinates.</li>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension6} since version 3.1
 * extending the text viewer with the ability to detect hyperlinks and access the undo manager.</li>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension7} since version 3.3
 * extending the text viewer with the ability to install tabs to spaces conversion.</li>
 * <li>{@link org.eclipse.jface.text.ITextViewerExtension8} since version 3.4
 * extending the text viewer with the ability to print and rich hover support.</li>
 * </ul></p>
 * <p>
 * Clients may implement this interface and its extension interfaces or use the
 * standard implementation {@link org.eclipse.jface.text.TextViewer}.</p>
 *
 * @see org.eclipse.jface.text.ITextViewerExtension
 * @see org.eclipse.jface.text.ITextViewerExtension2
 * @see org.eclipse.jface.text.ITextViewerExtension3
 * @see org.eclipse.jface.text.ITextViewerExtension4
 * @see org.eclipse.jface.text.ITextViewerExtension5
 * @see org.eclipse.jface.text.ITextViewerExtension6
 * @see org.eclipse.jface.text.ITextViewerExtension7
 * @see org.eclipse.jface.text.ITextViewerExtension8
 * @see org.eclipse.jface.text.IDocument
 * @see org.eclipse.jface.text.ITextInputListener
 * @see org.eclipse.jface.text.IViewportListener
 * @see org.eclipse.jface.text.ITextListener
 * @see org.eclipse.jface.text.IEventConsumer
 */
public interface ITextViewer {


	/* ---------- widget --------- */

	/**
	 * Returns this viewer's SWT control, <code>null</code> if the control is disposed.
	 * <p>
	 * <em>Calling API directly on the widget can interfere with features provided
	 * by a text viewer. Clients who call API directly on the widget are responsible
	 * to resolve such conflicts on their side.</em>
	 * </p>
	 *
	 * @return the SWT control or <code>null</code>
	 */
	StyledText getTextWidget();


	/* --------- plug-ins --------- */

	/**
	 * Sets this viewer's undo manager.
	 *
	 * @param undoManager the new undo manager. <code>null</code> is a valid argument.
	 */
	void setUndoManager(IUndoManager undoManager);

	/**
	 * Sets this viewer's text double click strategy for the given content type.
	 *
	 * @param strategy the new double click strategy. <code>null</code> is a valid argument.
	 * @param contentType the type for which the strategy is registered
	 */
	void setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy, String contentType);

	/**
	 * Sets this viewer's auto indent strategy for the given content type. If
	 * the given strategy is <code>null</code> any installed strategy for the
	 * content type is removed. This method has been replaced by
	 * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
	 * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)}.
	 * It is now equivalent to
	 * <pre>
	 * 		ITextViewerExtension2 extension= (ITextViewerExtension2) viewer;
	 * 		extension.removeAutoEditStrategy(oldStrategy, contentType);
	 * 		extension.prependAutoEditStrategy(strategy, contentType);
	 * </pre>
	 *
	 * @param strategy the new auto indent strategy. <code>null</code> is a
	 *            valid argument.
	 * @param contentType the type for which the strategy is registered
	 * @deprecated since 3.1, use
	 *             {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
	 *             {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)} instead
	 */
	@Deprecated
	void setAutoIndentStrategy(IAutoIndentStrategy strategy, String contentType);

	/**
	 * Sets this viewer's text hover for the given content type.
	 * <p>
	 * This method has been replaced by {@link ITextViewerExtension2#setTextHover(ITextHover, String, int)}.
	 * It is now equivalent to
	 * <pre>
	 *    ITextViewerExtension2 extension= (ITextViewerExtension2) document;
	 *    extension.setTextHover(textViewerHover, contentType, ITextViewerExtension2#DEFAULT_HOVER_STATE_MASK);
	 * </pre>
	 *
	 *
	 * @param textViewerHover the new hover. <code>null</code> is a valid
	 *            argument.
	 * @param contentType the type for which the hover is registered
	 */
	void setTextHover(ITextHover textViewerHover, String contentType);

	/**
	 * Activates the installed plug-ins. If the plug-ins are already activated
	 * this call has no effect.
	 */
	void activatePlugins();

	/**
	 * Resets the installed plug-ins. If plug-ins change their state or
	 * behavior over the course of time, this method causes them to be set
	 * back to their initial state and behavior. E.g., if an {@link IUndoManager}
	 * has been installed on this text viewer, the manager's list of remembered
     * text editing operations is removed.
	 */
	void resetPlugins();



	/* ---------- listeners ------------- */

	/**
	 * Adds the given view port listener to this viewer. If the listener is already registered with
	 * this viewer, this call has no effect.
	 * 
	 * @param listener the listener to be added
	 */
	void addViewportListener(IViewportListener listener);

	/**
	 * Removes the given listener from this viewer's set of view port listeners.
	 * If the listener is not registered with this viewer, this call has
	 * no effect.
	 *
	 * @param listener the listener to be removed
	 */
	void removeViewportListener(IViewportListener listener);

	/**
	 * Adds a text listener to this viewer. If the listener is already registered
	 * with this viewer, this call has no effect.
	 *
	 * @param listener the listener to be added
	 */
	void addTextListener(ITextListener listener);

	/**
	 * Removes the given listener from this viewer's set of text listeners.
	 * If the listener is not registered with this viewer, this call has
	 * no effect.
	 *
	 * @param listener the listener to be removed
	 */
	void removeTextListener(ITextListener listener);

	/**
	 * Adds a text input listener to this viewer. If the listener is already registered
	 * with this viewer, this call has no effect.
	 *
	 * @param listener the listener to be added
	 */
	void addTextInputListener(ITextInputListener listener);

	/**
	 * Removes the given listener from this viewer's set of text input listeners.
	 * If the listener is not registered with this viewer, this call has
	 * no effect.
	 *
	 * @param listener the listener to be removed
	 */
	void removeTextInputListener(ITextInputListener listener);



	/* -------------- model manipulation ------------- */

	/**
	 * Sets the given document as the text viewer's model and updates the
	 * presentation accordingly. An appropriate <code>TextEvent</code> is
	 * issued. This text event does not carry a related document event.
	 *
	 * @param document the viewer's new input document <code>null</code> if none
	 */
	void setDocument(IDocument document);

	/**
	 * Returns the text viewer's input document.
	 *
	 * @return the viewer's input document or <code>null</code> if none
	 */
	IDocument getDocument();


	/* -------------- event handling ----------------- */

	/**
	 * Registers an event consumer with this viewer. This method has been
	 * replaces with the {@link org.eclipse.swt.custom.VerifyKeyListener}
	 * management methods in {@link ITextViewerExtension}.
	 *
	 * @param consumer the viewer's event consumer. <code>null</code> is a
	 *            valid argument.
	 */
	void setEventConsumer(IEventConsumer consumer);

	/**
	 * Sets the editable state.
	 *
	 * @param editable the editable state
	 */
	void setEditable(boolean editable);

	/**
	 * Returns whether the shown text can be manipulated.
	 *
	 * @return the viewer's editable state
	 */
	boolean isEditable();


	/* ----------- visible region support ------------- */

	/**
	 * Sets the given document as this viewer's model and
	 * exposes the specified region. An appropriate
	 * <code>TextEvent</code> is issued. The text event does not carry a
	 * related document event. This method is a convenience method for
	 * <code>setDocument(document);setVisibleRegion(offset, length)</code>.
	 *
	 * @param document the new input document or <code>null</code> if none
	 * @param modelRangeOffset the offset of the model range
	 * @param modelRangeLength the length of the model range
	 */
	void setDocument(IDocument document, int modelRangeOffset, int modelRangeLength);

	/**
	 * Defines and sets the region of this viewer's document which will be
	 * visible in the presentation. Every character inside the specified region
	 * is supposed to be visible in the viewer's widget after that call.
	 *
	 * @param offset the offset of the visible region
	 * @param length the length of the visible region
	 */
	void setVisibleRegion(int offset, int length);

	/**
	 * Resets the region of this viewer's document which is visible in the presentation.
	 * Afterwards, the whole input document is visible.
	 */
	void resetVisibleRegion();

	/**
	 * Returns the current visible region of this viewer's document. The result
	 * may differ from the argument passed to <code>setVisibleRegion</code> if
	 * the document has been modified since then. The visible region is supposed
	 * to be a consecutive region in viewer's input document and every character
	 * inside that region is supposed to visible in the viewer's widget.
	 * <p>
	 * Viewers implementing {@link ITextViewerExtension5} may be forced to
	 * change the fractions of the input document that are shown, in order to
	 * fulfill this contract.
	 *
	 * @return this viewer's current visible region
	 */
	IRegion getVisibleRegion();

	/**
	 * Returns whether a given range overlaps with the visible region of this
	 * viewer's document.
	 * <p>
	 * Viewers implementing {@link ITextViewerExtension5}may be forced to
	 * change the fractions of the input document that are shown in order to
	 * fulfill this request. This is because the overlap is supposed to be
	 * without gaps.
	 *
	 * @param offset the offset
	 * @param length the length
	 * @return <code>true</code> if the specified range overlaps with the
	 *         visible region
	 */
	boolean overlapsWithVisibleRegion(int offset, int length);



	/* ------------- presentation manipulation ----------- */

	/**
	 * Applies the color information encoded in the given text presentation.
	 * <code>controlRedraw</code> tells this viewer whether it should take care of
	 * redraw management or not. If, e.g., this call is one in a sequence of multiple
	 * presentation calls, it is more appropriate to explicitly control redrawing at the
	 * beginning and the end of the sequence.
	 *
	 * @param presentation the presentation to be applied to this viewer
	 * @param controlRedraw indicates whether this viewer should manage redraws
	 */
	void changeTextPresentation(TextPresentation presentation, boolean controlRedraw);

	/**
	 * Marks the currently applied text presentation as invalid. It is the
	 * viewer's responsibility to take any action it can to repair the text
	 * presentation.
	 * <p>
	 * See {@link ITextViewerExtension2#invalidateTextPresentation(int, int)}
	 * for a way to invalidate specific regions rather than the presentation as
	 * a whole.
	 *
	 * @since 2.0
	 */
	void invalidateTextPresentation();

	/**
	 * Applies the given color as text foreground color to this viewer's
	 * selection.
	 *
	 * @param color the color to be applied
	 */
	void setTextColor(Color color);

	/**
	 * Applies the given color as text foreground color to the specified section
	 * of this viewer. <code>controlRedraw</code> tells this viewer whether it
	 * should take care of redraw management or not.
	 *
	 * @param color the color to be applied
	 * @param offset the offset of the range to be changed
	 * @param length the length of the range to be changed
	 * @param controlRedraw indicates whether this viewer should manage redraws
	 */
	void setTextColor(Color color, int offset, int length, boolean controlRedraw);


	/* --------- target handling and configuration ------------ */

	/**
	 * Returns the text operation target of this viewer.
	 *
	 * @return the text operation target of this viewer
	 */
	ITextOperationTarget getTextOperationTarget();

	/**
	 * Returns the find/replace operation target of this viewer.
	 *
	 * @return the find/replace operation target of this viewer
	 */
	IFindReplaceTarget getFindReplaceTarget();

	/**
	 * Sets the strings that are used as prefixes when lines of the given content type
	 * are prefixed using the prefix text operation. The prefixes are considered equivalent.
	 * Inserting a prefix always inserts the defaultPrefixes[0].
	 * Removing a prefix removes all of the specified prefixes.
	 *
	 * @param defaultPrefixes the prefixes to be used
	 * @param contentType the content type for which the prefixes are specified
	 * @since 2.0
	 */
	void setDefaultPrefixes(String[] defaultPrefixes, String contentType);

	/**
	 * Sets the strings that are used as prefixes when lines of the given content type
	 * are shifted using the shift text operation. The prefixes are considered equivalent.
	 * Thus "\t" and "    " can both be used as prefix characters.
	 * Shift right always inserts the indentPrefixes[0].
	 * Shift left removes all of the specified prefixes.
	 *
	 * @param indentPrefixes the prefixes to be used
	 * @param contentType the content type for which the prefixes are specified
	 */
	void setIndentPrefixes(String[] indentPrefixes, String contentType);



	/* --------- selection handling -------------- */

	/**
	 * Sets the selection to the specified range.
	 *
	 * @param offset the offset of the selection range
	 * @param length the length of the selection range. A negative length places
	 *            the caret at the visual start of the selection.
	 */
	void setSelectedRange(int offset, int length);

	/**
	 * Returns the range of the current selection in coordinates of this viewer's document.
	 *
	 * @return a <code>Point</code> with x as the offset and y as the length of the current selection
	 */
	Point getSelectedRange();

	/**
	 * Returns a selection provider dedicated to this viewer. Subsequent
	 * calls to this method return always the same selection provider.
	 *
	 * @return this viewer's selection provider
	 */
	ISelectionProvider getSelectionProvider();


	/* ------------- appearance manipulation --------------- */

	/**
	 * Ensures that the given range is visible.
	 *
	 * @param offset the offset of the range to be revealed
	 * @param length the length of the range to be revealed
	 */
	void revealRange(int offset, int length);

	/**
	 * Scrolls the widget so that the given index is the line
	 * with the smallest line number of all visible lines.
	 *
	 * @param index the line which should become the top most line
	 */
	void setTopIndex(int index);

	/**
	 * Returns the visible line with the smallest line number.
	 *
	 * @return the number of the top most visible line
	 */
	int getTopIndex();

	/**
	 * Returns the document offset of the upper left corner of this viewer's view port.
	 *
	 * @return the upper left corner offset
	 */
	int getTopIndexStartOffset();

	/**
	 * Returns the visible line with the highest line number.
	 *
	 * @return the number of the bottom most line
	 */
	int getBottomIndex();

	/**
	 * Returns the document offset of the lower right
	 * corner of this viewer's view port. This is the visible character
	 * with the highest character position. If the content of this viewer
	 * is shorter, the position of the last character of the content is returned.
	 *
	 * @return the lower right corner offset
	 */
	int getBottomIndexEndOffset();

	/**
	 * Returns the vertical offset of the first visible line.
	 *
	 * @return the vertical offset of the first visible line
	 */
	int getTopInset();
}

Back to the top