KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > text > ITextViewer


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 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 import org.eclipse.swt.custom.StyledText;
14 import org.eclipse.swt.graphics.Color;
15 import org.eclipse.swt.graphics.Point;
16
17 import org.eclipse.jface.viewers.ISelectionProvider;
18
19
20 /**
21  * A text viewer connects a text widget with an
22  * {@link org.eclipse.jface.text.IDocument}. The document is used as the
23  * widget's text model.
24  * <p>
25  * It supports the following kinds of listeners:
26  * <ul>
27  * <li>view port listeners to inform about changes of the viewer's view port</li>
28  * <li>text listeners to inform about changes of the document and the
29  * subsequent viewer change</li>
30  * <li>text input listeners to inform about changes of the viewer's input
31  * document.</li>
32  * </ul>
33  * A text viewer supports a set of configuration options and plug-ins defining
34  * its behavior:
35  * <ul>
36  * <li>undo manager</li>
37  * <li>double click behavior</li>
38  * <li>auto indentation</li>
39  * <li>text hover</li>
40  * </ul>
41  * Installed plug-ins are not automatically activated. Plug-ins must be
42  * activated with the <code>activatePlugins</code> call. Most plug-ins can be
43  * defined per content type. Content types are derived from a partitioning of
44  * the text viewer's input document. In case of documents that support multiple
45  * partitionings, the implementer is responsible for determining the
46  * partitioning to use.
47  * <p>
48  * A text viewer also provides the concept of event consumption. Events handled
49  * by the viewer can be filtered and processed by a dynamic event consumer. With
50  * {@link org.eclipse.jface.text.ITextViewerExtension}this mechanism has been
51  * replaced with the support for
52  * {@link org.eclipse.swt.custom.VerifyKeyListener}.
53  * <p>
54  * A text viewer provides several text editing functions, some of them are
55  * configurable, through a text operation target interface. It also supports a
56  * presentation mode in which it only shows a specified section of its document.
57  * By calling <code>setVisibleRegion</code> clients define which section is
58  * visible. Clients can get access to this section by calling
59  * <code>getVisibleRegion</code>. The viewer's presentation mode does not
60  * affect any client of the viewer other than text listeners. With
61  * {@link org.eclipse.jface.text.ITextViewerExtension5} the visible region
62  * support has been reworked. With that extension interface, text viewers are
63  * allowed to show fractions of their input document. I.e. a widget selection of
64  * two visually neighboring characters is no longer guaranteed to be two
65  * neighboring characters in the viewer's input document. Thus, viewers
66  * implementing {@link org.eclipse.jface.text.ITextViewerExtension5} are
67  * potentially forced to change the fractions of the input document that are
68  * shown when clients ask for the visible region.
69  * <p>
70  *
71  * In order to provide backward compatibility for clients of
72  * <code>ITextViewer</code>, extension interfaces are used as a means of
73  * evolution. The following extension interfaces exist:
74  * <ul>
75  * <li>{@link org.eclipse.jface.text.ITextViewerExtension} since version 2.0
76  * replacing the event consumer mechanism and introducing the concept of rewrite
77  * targets and means to manage the viewer's redraw behavior</li>
78  * <li>{@link org.eclipse.jface.text.ITextViewerExtension2}since version 2.1
79  * adding a way to invalidate a viewer's presentation and setters for hovers.
80  * </li>
81  * <li>{@link org.eclipse.jface.text.ITextViewerExtension3} since version 2.1
82  * which itself was replaced by
83  * {@link org.eclipse.jface.text.ITextViewerExtension5} in version 3.0</li>
84  * <li>{@link org.eclipse.jface.text.ITextViewerExtension4} since version 3.0
85  * introducing focus handling for widget token keepers and the concept of text
86  * presentation listeners.</li>
87  * <li>{@link org.eclipse.jface.text.ITextViewerExtension5} since version 3.0
88  * extending the visible region concept with explicit handling and conversation
89  * of widget and model coordinates.</li>
90  * <li>{@link org.eclipse.jface.text.ITextViewerExtension6} since version 3.1
91  * extending the text viewer with the ability to detect hyperlinks and access the undo manager.</li>
92  * <li>{@link org.eclipse.jface.text.ITextViewerExtension7} since version 3.3
93  * extending the text viewer with the ability to install tabs to spaces conversion.</li>
94  * </ul></p>
95  * <p>
96  * Clients may implement this interface and its extension interfaces or use the
97  * standard implementation {@link org.eclipse.jface.text.TextViewer}.</p>
98  *
99  * @see org.eclipse.jface.text.ITextViewerExtension
100  * @see org.eclipse.jface.text.ITextViewerExtension2
101  * @see org.eclipse.jface.text.ITextViewerExtension3
102  * @see org.eclipse.jface.text.ITextViewerExtension4
103  * @see org.eclipse.jface.text.ITextViewerExtension5
104  * @see org.eclipse.jface.text.ITextViewerExtension6
105  * @see org.eclipse.jface.text.ITextViewerExtension7
106  * @see org.eclipse.jface.text.IDocument
107  * @see org.eclipse.jface.text.ITextInputListener
108  * @see org.eclipse.jface.text.IViewportListener
109  * @see org.eclipse.jface.text.ITextListener
110  * @see org.eclipse.jface.text.IEventConsumer
111  */

112 public interface ITextViewer {
113
114
115     /* ---------- widget --------- */
116
117     /**
118      * Returns this viewer's SWT control, <code>null</code> if the control is disposed.
119      * <p>
120      * <em>Calling API directly on the widget can interfere with features provided
121      * by a text viewer. Clients who call API directly on the widget are responsible
122      * to resolve such conflicts on their side.</em>
123      * </p>
124      *
125      * @return the SWT control or <code>null</code>
126      */

127     StyledText getTextWidget();
128
129
130     /* --------- plug-ins --------- */
131
132     /**
133      * Sets this viewer's undo manager.
134      *
135      * @param undoManager the new undo manager. <code>null</code> is a valid argument.
136      */

137     void setUndoManager(IUndoManager undoManager);
138
139     /**
140      * Sets this viewer's text double click strategy for the given content type.
141      *
142      * @param strategy the new double click strategy. <code>null</code> is a valid argument.
143      * @param contentType the type for which the strategy is registered
144      */

145     void setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy, String JavaDoc contentType);
146
147     /**
148      * Sets this viewer's auto indent strategy for the given content type. If
149      * the given strategy is <code>null</code> any installed strategy for the
150      * content type is removed. This method has been replaced by
151      * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
152      * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)}.
153      * It is now equivalent to
154      * <pre>
155      * ITextViewerExtension2 extension= (ITextViewerExtension2) viewer;
156      * extension.removeAutoEditStrategy(oldStrategy, contentType);
157      * extension.prependAutoEditStrategy(strategy, contentType);
158      * </pre>
159      *
160      * @param strategy the new auto indent strategy. <code>null</code> is a
161      * valid argument.
162      * @param contentType the type for which the strategy is registered
163      * @deprecated since 3.1, use
164      * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
165      * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)} instead
166      */

167     void setAutoIndentStrategy(IAutoIndentStrategy strategy, String JavaDoc contentType);
168
169     /**
170      * Sets this viewer's text hover for the given content type.
171      * <p>
172      * This method has been replaced by {@link ITextViewerExtension2#setTextHover(ITextHover, String, int)}.
173      * It is now equivalent to
174      * <pre>
175      * ITextViewerExtension2 extension= (ITextViewerExtension2) document;
176      * extension.setTextHover(textViewerHover, contentType, ITextViewerExtension2#DEFAULT_HOVER_STATE_MASK);
177      * </pre>
178      *
179      *
180      * @param textViewerHover the new hover. <code>null</code> is a valid
181      * argument.
182      * @param contentType the type for which the hover is registered
183      */

184     void setTextHover(ITextHover textViewerHover, String JavaDoc contentType);
185
186     /**
187      * Activates the installed plug-ins. If the plug-ins are already activated
188      * this call has no effect.
189      */

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

199     void resetPlugins();
200
201
202
203     /* ---------- listeners ------------- */
204
205     /**
206      * Adds the given view port listener to this viewer. The listener
207      * is informed about all changes to the visible area of this viewer.
208      * If the listener is already registered with this viewer, this call
209      * has no effect.
210      *
211      * @param listener the listener to be added
212      */

213     void addViewportListener(IViewportListener listener);
214
215     /**
216      * Removes the given listener from this viewer's set of view port listeners.
217      * If the listener is not registered with this viewer, this call has
218      * no effect.
219      *
220      * @param listener the listener to be removed
221      */

222     void removeViewportListener(IViewportListener listener);
223
224     /**
225      * Adds a text listener to this viewer. If the listener is already registered
226      * with this viewer, this call has no effect.
227      *
228      * @param listener the listener to be added
229      */

230     void addTextListener(ITextListener listener);
231
232     /**
233      * Removes the given listener from this viewer's set of text listeners.
234      * If the listener is not registered with this viewer, this call has
235      * no effect.
236      *
237      * @param listener the listener to be removed
238      */

239     void removeTextListener(ITextListener listener);
240
241     /**
242      * Adds a text input listener to this viewer. If the listener is already registered
243      * with this viewer, this call has no effect.
244      *
245      * @param listener the listener to be added
246      */

247     void addTextInputListener(ITextInputListener listener);
248
249     /**
250      * Removes the given listener from this viewer's set of text input listeners.
251      * If the listener is not registered with this viewer, this call has
252      * no effect.
253      *
254      * @param listener the listener to be removed
255      */

256     void removeTextInputListener(ITextInputListener listener);
257
258
259
260     /* -------------- model manipulation ------------- */
261
262     /**
263      * Sets the given document as the text viewer's model and updates the
264      * presentation accordingly. An appropriate <code>TextEvent</code> is
265      * issued. This text event does not carry a related document event.
266      *
267      * @param document the viewer's new input document <code>null</code> if none
268      */

269     void setDocument(IDocument document);
270
271     /**
272      * Returns the text viewer's input document.
273      *
274      * @return the viewer's input document or <code>null</code> if none
275      */

276     IDocument getDocument();
277
278
279     /* -------------- event handling ----------------- */
280
281     /**
282      * Registers an event consumer with this viewer. This method has been
283      * replaces with the {@link org.eclipse.swt.custom.VerifyKeyListener}
284      * management methods in {@link ITextViewerExtension}.
285      *
286      * @param consumer the viewer's event consumer. <code>null</code> is a
287      * valid argument.
288      */

289     void setEventConsumer(IEventConsumer consumer);
290
291     /**
292      * Sets the editable state.
293      *
294      * @param editable the editable state
295      */

296     void setEditable(boolean editable);
297
298     /**
299      * Returns whether the shown text can be manipulated.
300      *
301      * @return the viewer's editable state
302      */

303     boolean isEditable();
304
305
306     /* ----------- visible region support ------------- */
307
308     /**
309      * Sets the given document as this viewer's model and
310      * exposes the specified region. An appropriate
311      * <code>TextEvent</code> is issued. The text event does not carry a
312      * related document event. This method is a convenience method for
313      * <code>setDocument(document);setVisibleRegion(offset, length)</code>.
314      *
315      * @param document the new input document or <code>null</code> if none
316      * @param modelRangeOffset the offset of the model range
317      * @param modelRangeLength the length of the model range
318      */

319     void setDocument(IDocument document, int modelRangeOffset, int modelRangeLength);
320
321     /**
322      * Defines and sets the region of this viewer's document which will be
323      * visible in the presentation. Every character inside the specified region
324      * is supposed to be visible in the viewer's widget after that call.
325      *
326      * @param offset the offset of the visible region
327      * @param length the length of the visible region
328      */

329     void setVisibleRegion(int offset, int length);
330
331     /**
332      * Resets the region of this viewer's document which is visible in the presentation.
333      * Afterwards, the whole input document is visible.
334      */

335     void resetVisibleRegion();
336
337     /**
338      * Returns the current visible region of this viewer's document. The result
339      * may differ from the argument passed to <code>setVisibleRegion</code> if
340      * the document has been modified since then. The visible region is supposed
341      * to be a consecutive region in viewer's input document and every character
342      * inside that region is supposed to visible in the viewer's widget.
343      * <p>
344      * Viewers implementing {@link ITextViewerExtension5} may be forced to
345      * change the fractions of the input document that are shown, in order to
346      * fulfill this contract.
347      *
348      * @return this viewer's current visible region
349      */

350     IRegion getVisibleRegion();
351
352     /**
353      * Returns whether a given range overlaps with the visible region of this
354      * viewer's document.
355      * <p>
356      * Viewers implementing {@link ITextViewerExtension5}may be forced to
357      * change the fractions of the input document that are shown in order to
358      * fulfill this request. This is because the overlap is supposed to be
359      * without gaps.
360      *
361      * @param offset the offset
362      * @param length the length
363      * @return <code>true</code> if the specified range overlaps with the
364      * visible region
365      */

366     boolean overlapsWithVisibleRegion(int offset, int length);
367
368
369
370     /* ------------- presentation manipulation ----------- */
371
372     /**
373      * Applies the color information encoded in the given text presentation.
374      * <code>controlRedraw</code> tells this viewer whether it should take care of
375      * redraw management or not. If, e.g., this call is one in a sequence of multiple
376      * presentation calls, it is more appropriate to explicitly control redrawing at the
377      * beginning and the end of the sequence.
378      *
379      * @param presentation the presentation to be applied to this viewer
380      * @param controlRedraw indicates whether this viewer should manage redraws
381      */

382     void changeTextPresentation(TextPresentation presentation, boolean controlRedraw);
383
384     /**
385      * Marks the currently applied text presentation as invalid. It is the
386      * viewer's responsibility to take any action it can to repair the text
387      * presentation.
388      * <p>
389      * See {@link ITextViewerExtension2#invalidateTextPresentation(int, int)}
390      * for a way to invalidate specific regions rather than the presentation as
391      * a whole.
392      *
393      * @since 2.0
394      */

395     void invalidateTextPresentation();
396
397     /**
398      * Applies the given color as text foreground color to this viewer's
399      * selection.
400      *
401      * @param color the color to be applied
402      */

403     void setTextColor(Color color);
404
405     /**
406      * Applies the given color as text foreground color to the specified section
407      * of this viewer. <code>controlRedraw</code> tells this viewer whether it
408      * should take care of redraw management or not.
409      *
410      * @param color the color to be applied
411      * @param offset the offset of the range to be changed
412      * @param length the length of the range to be changed
413      * @param controlRedraw indicates whether this viewer should manage redraws
414      */

415     void setTextColor(Color color, int offset, int length, boolean controlRedraw);
416
417
418     /* --------- target handling and configuration ------------ */
419
420     /**
421      * Returns the text operation target of this viewer.
422      *
423      * @return the text operation target of this viewer
424      */

425     ITextOperationTarget getTextOperationTarget();
426
427     /**
428      * Returns the find/replace operation target of this viewer.
429      *
430      * @return the find/replace operation target of this viewer
431      */

432     IFindReplaceTarget getFindReplaceTarget();
433
434     /**
435      * Sets the strings that are used as prefixes when lines of the given content type
436      * are prefixed using the prefix text operation. The prefixes are considered equivalent.
437      * Inserting a prefix always inserts the defaultPrefixes[0].
438      * Removing a prefix removes all of the specified prefixes.
439      *
440      * @param defaultPrefixes the prefixes to be used
441      * @param contentType the content type for which the prefixes are specified
442      * @since 2.0
443      */

444     void setDefaultPrefixes(String JavaDoc[] defaultPrefixes, String JavaDoc contentType);
445
446     /**
447      * Sets the strings that are used as prefixes when lines of the given content type
448      * are shifted using the shift text operation. The prefixes are considered equivalent.
449      * Thus "\t" and " " can both be used as prefix characters.
450      * Shift right always inserts the indentPrefixes[0].
451      * Shift left removes all of the specified prefixes.
452      *
453      * @param indentPrefixes the prefixes to be used
454      * @param contentType the content type for which the prefixes are specified
455      */

456     void setIndentPrefixes(String JavaDoc[] indentPrefixes, String JavaDoc contentType);
457
458
459
460     /* --------- selection handling -------------- */
461
462     /**
463      * Sets the selection to the specified range.
464      *
465      * @param offset the offset of the selection range
466      * @param length the length of the selection range
467      */

468     void setSelectedRange(int offset, int length);
469
470     /**
471      * Returns the range of the current selection in coordinates of this viewer's document.
472      *
473      * @return a <code>Point</code> with x as the offset and y as the length of the current selection
474      */

475     Point getSelectedRange();
476
477     /**
478      * Returns a selection provider dedicated to this viewer. Subsequent
479      * calls to this method return always the same selection provider.
480      *
481      * @return this viewer's selection provider
482      */

483     ISelectionProvider getSelectionProvider();
484
485
486     /* ------------- appearance manipulation --------------- */
487
488     /**
489      * Ensures that the given range is visible.
490      *
491      * @param offset the offset of the range to be revealed
492      * @param length the length of the range to be revealed
493      */

494     void revealRange(int offset, int length);
495
496     /**
497      * Scrolls the widget so that the given index is the line
498      * with the smallest line number of all visible lines.
499      *
500      * @param index the line which should become the top most line
501      */

502     void setTopIndex(int index);
503
504     /**
505      * Returns the visible line with the smallest line number.
506      *
507      * @return the number of the top most visible line
508      */

509     int getTopIndex();
510
511     /**
512      * Returns the document offset of the upper left corner of this viewer's view port.
513      *
514      * @return the upper left corner offset
515      */

516     int getTopIndexStartOffset();
517
518     /**
519      * Returns the visible line with the highest line number.
520      *
521      * @return the number of the bottom most line
522      */

523     int getBottomIndex();
524
525     /**
526      * Returns the document offset of the lower right
527      * corner of this viewer's view port. This is the visible character
528      * with the highest character position. If the content of this viewer
529      * is shorter, the position of the last character of the content is returned.
530      *
531      * @return the lower right corner offset
532      */

533     int getBottomIndexEndOffset();
534
535     /**
536      * Returns the vertical offset of the first visible line.
537      *
538      * @return the vertical offset of the first visible line
539      */

540     int getTopInset();
541 }
542
Popular Tags