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   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   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   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  [] defaultPrefixes, String   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  [] indentPrefixes, String   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags