001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text;
011:
012: import org.eclipse.swt.custom.StyledText;
013: import org.eclipse.swt.graphics.Color;
014: import org.eclipse.swt.graphics.Point;
015:
016: import org.eclipse.jface.viewers.ISelectionProvider;
017:
018: /**
019: * A text viewer connects a text widget with an
020: * {@link org.eclipse.jface.text.IDocument}. The document is used as the
021: * widget's text model.
022: * <p>
023: * It supports the following kinds of listeners:
024: * <ul>
025: * <li>view port listeners to inform about changes of the viewer's view port</li>
026: * <li>text listeners to inform about changes of the document and the
027: * subsequent viewer change</li>
028: * <li>text input listeners to inform about changes of the viewer's input
029: * document.</li>
030: * </ul>
031: * A text viewer supports a set of configuration options and plug-ins defining
032: * its behavior:
033: * <ul>
034: * <li>undo manager</li>
035: * <li>double click behavior</li>
036: * <li>auto indentation</li>
037: * <li>text hover</li>
038: * </ul>
039: * Installed plug-ins are not automatically activated. Plug-ins must be
040: * activated with the <code>activatePlugins</code> call. Most plug-ins can be
041: * defined per content type. Content types are derived from a partitioning of
042: * the text viewer's input document. In case of documents that support multiple
043: * partitionings, the implementer is responsible for determining the
044: * partitioning to use.
045: * <p>
046: * A text viewer also provides the concept of event consumption. Events handled
047: * by the viewer can be filtered and processed by a dynamic event consumer. With
048: * {@link org.eclipse.jface.text.ITextViewerExtension}this mechanism has been
049: * replaced with the support for
050: * {@link org.eclipse.swt.custom.VerifyKeyListener}.
051: * <p>
052: * A text viewer provides several text editing functions, some of them are
053: * configurable, through a text operation target interface. It also supports a
054: * presentation mode in which it only shows a specified section of its document.
055: * By calling <code>setVisibleRegion</code> clients define which section is
056: * visible. Clients can get access to this section by calling
057: * <code>getVisibleRegion</code>. The viewer's presentation mode does not
058: * affect any client of the viewer other than text listeners. With
059: * {@link org.eclipse.jface.text.ITextViewerExtension5} the visible region
060: * support has been reworked. With that extension interface, text viewers are
061: * allowed to show fractions of their input document. I.e. a widget selection of
062: * two visually neighboring characters is no longer guaranteed to be two
063: * neighboring characters in the viewer's input document. Thus, viewers
064: * implementing {@link org.eclipse.jface.text.ITextViewerExtension5} are
065: * potentially forced to change the fractions of the input document that are
066: * shown when clients ask for the visible region.
067: * <p>
068: *
069: * In order to provide backward compatibility for clients of
070: * <code>ITextViewer</code>, extension interfaces are used as a means of
071: * evolution. The following extension interfaces exist:
072: * <ul>
073: * <li>{@link org.eclipse.jface.text.ITextViewerExtension} since version 2.0
074: * replacing the event consumer mechanism and introducing the concept of rewrite
075: * targets and means to manage the viewer's redraw behavior</li>
076: * <li>{@link org.eclipse.jface.text.ITextViewerExtension2}since version 2.1
077: * adding a way to invalidate a viewer's presentation and setters for hovers.
078: * </li>
079: * <li>{@link org.eclipse.jface.text.ITextViewerExtension3} since version 2.1
080: * which itself was replaced by
081: * {@link org.eclipse.jface.text.ITextViewerExtension5} in version 3.0</li>
082: * <li>{@link org.eclipse.jface.text.ITextViewerExtension4} since version 3.0
083: * introducing focus handling for widget token keepers and the concept of text
084: * presentation listeners.</li>
085: * <li>{@link org.eclipse.jface.text.ITextViewerExtension5} since version 3.0
086: * extending the visible region concept with explicit handling and conversation
087: * of widget and model coordinates.</li>
088: * <li>{@link org.eclipse.jface.text.ITextViewerExtension6} since version 3.1
089: * extending the text viewer with the ability to detect hyperlinks and access the undo manager.</li>
090: * <li>{@link org.eclipse.jface.text.ITextViewerExtension7} since version 3.3
091: * extending the text viewer with the ability to install tabs to spaces conversion.</li>
092: * </ul></p>
093: * <p>
094: * Clients may implement this interface and its extension interfaces or use the
095: * standard implementation {@link org.eclipse.jface.text.TextViewer}.</p>
096: *
097: * @see org.eclipse.jface.text.ITextViewerExtension
098: * @see org.eclipse.jface.text.ITextViewerExtension2
099: * @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.ITextViewerExtension6
103: * @see org.eclipse.jface.text.ITextViewerExtension7
104: * @see org.eclipse.jface.text.IDocument
105: * @see org.eclipse.jface.text.ITextInputListener
106: * @see org.eclipse.jface.text.IViewportListener
107: * @see org.eclipse.jface.text.ITextListener
108: * @see org.eclipse.jface.text.IEventConsumer
109: */
110: public interface ITextViewer {
111:
112: /* ---------- widget --------- */
113:
114: /**
115: * Returns this viewer's SWT control, <code>null</code> if the control is disposed.
116: * <p>
117: * <em>Calling API directly on the widget can interfere with features provided
118: * by a text viewer. Clients who call API directly on the widget are responsible
119: * to resolve such conflicts on their side.</em>
120: * </p>
121: *
122: * @return the SWT control or <code>null</code>
123: */
124: StyledText getTextWidget();
125:
126: /* --------- plug-ins --------- */
127:
128: /**
129: * Sets this viewer's undo manager.
130: *
131: * @param undoManager the new undo manager. <code>null</code> is a valid argument.
132: */
133: void setUndoManager(IUndoManager undoManager);
134:
135: /**
136: * Sets this viewer's text double click strategy for the given content type.
137: *
138: * @param strategy the new double click strategy. <code>null</code> is a valid argument.
139: * @param contentType the type for which the strategy is registered
140: */
141: void setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy,
142: String contentType);
143:
144: /**
145: * Sets this viewer's auto indent strategy for the given content type. If
146: * the given strategy is <code>null</code> any installed strategy for the
147: * content type is removed. This method has been replaced by
148: * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
149: * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)}.
150: * It is now equivalent to
151: * <pre>
152: * ITextViewerExtension2 extension= (ITextViewerExtension2) viewer;
153: * extension.removeAutoEditStrategy(oldStrategy, contentType);
154: * extension.prependAutoEditStrategy(strategy, contentType);
155: * </pre>
156: *
157: * @param strategy the new auto indent strategy. <code>null</code> is a
158: * valid argument.
159: * @param contentType the type for which the strategy is registered
160: * @deprecated since 3.1, use
161: * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and
162: * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)} instead
163: */
164: void setAutoIndentStrategy(IAutoIndentStrategy strategy,
165: String contentType);
166:
167: /**
168: * Sets this viewer's text hover for the given content type.
169: * <p>
170: * This method has been replaced by {@link ITextViewerExtension2#setTextHover(ITextHover, String, int)}.
171: * It is now equivalent to
172: * <pre>
173: * ITextViewerExtension2 extension= (ITextViewerExtension2) document;
174: * extension.setTextHover(textViewerHover, contentType, ITextViewerExtension2#DEFAULT_HOVER_STATE_MASK);
175: * </pre>
176: *
177: *
178: * @param textViewerHover the new hover. <code>null</code> is a valid
179: * argument.
180: * @param contentType the type for which the hover is registered
181: */
182: void setTextHover(ITextHover textViewerHover, String contentType);
183:
184: /**
185: * Activates the installed plug-ins. If the plug-ins are already activated
186: * this call has no effect.
187: */
188: void activatePlugins();
189:
190: /**
191: * Resets the installed plug-ins. If plug-ins change their state or
192: * behavior over the course of time, this method causes them to be set
193: * back to their initial state and behavior. E.g., if an {@link IUndoManager}
194: * has been installed on this text viewer, the manager's list of remembered
195: * text editing operations is removed.
196: */
197: void resetPlugins();
198:
199: /* ---------- listeners ------------- */
200:
201: /**
202: * Adds the given view port listener to this viewer. The listener
203: * is informed about all changes to the visible area of this viewer.
204: * If the listener is already registered with this viewer, this call
205: * has no effect.
206: *
207: * @param listener the listener to be added
208: */
209: void addViewportListener(IViewportListener listener);
210:
211: /**
212: * Removes the given listener from this viewer's set of view port listeners.
213: * If the listener is not registered with this viewer, this call has
214: * no effect.
215: *
216: * @param listener the listener to be removed
217: */
218: void removeViewportListener(IViewportListener listener);
219:
220: /**
221: * Adds a text listener to this viewer. If the listener is already registered
222: * with this viewer, this call has no effect.
223: *
224: * @param listener the listener to be added
225: */
226: void addTextListener(ITextListener listener);
227:
228: /**
229: * Removes the given listener from this viewer's set of text listeners.
230: * If the listener is not registered with this viewer, this call has
231: * no effect.
232: *
233: * @param listener the listener to be removed
234: */
235: void removeTextListener(ITextListener listener);
236:
237: /**
238: * Adds a text input listener to this viewer. If the listener is already registered
239: * with this viewer, this call has no effect.
240: *
241: * @param listener the listener to be added
242: */
243: void addTextInputListener(ITextInputListener listener);
244:
245: /**
246: * Removes the given listener from this viewer's set of text input listeners.
247: * If the listener is not registered with this viewer, this call has
248: * no effect.
249: *
250: * @param listener the listener to be removed
251: */
252: void removeTextInputListener(ITextInputListener listener);
253:
254: /* -------------- model manipulation ------------- */
255:
256: /**
257: * Sets the given document as the text viewer's model and updates the
258: * presentation accordingly. An appropriate <code>TextEvent</code> is
259: * issued. This text event does not carry a related document event.
260: *
261: * @param document the viewer's new input document <code>null</code> if none
262: */
263: void setDocument(IDocument document);
264:
265: /**
266: * Returns the text viewer's input document.
267: *
268: * @return the viewer's input document or <code>null</code> if none
269: */
270: IDocument getDocument();
271:
272: /* -------------- event handling ----------------- */
273:
274: /**
275: * Registers an event consumer with this viewer. This method has been
276: * replaces with the {@link org.eclipse.swt.custom.VerifyKeyListener}
277: * management methods in {@link ITextViewerExtension}.
278: *
279: * @param consumer the viewer's event consumer. <code>null</code> is a
280: * valid argument.
281: */
282: void setEventConsumer(IEventConsumer consumer);
283:
284: /**
285: * Sets the editable state.
286: *
287: * @param editable the editable state
288: */
289: void setEditable(boolean editable);
290:
291: /**
292: * Returns whether the shown text can be manipulated.
293: *
294: * @return the viewer's editable state
295: */
296: boolean isEditable();
297:
298: /* ----------- visible region support ------------- */
299:
300: /**
301: * Sets the given document as this viewer's model and
302: * exposes the specified region. An appropriate
303: * <code>TextEvent</code> is issued. The text event does not carry a
304: * related document event. This method is a convenience method for
305: * <code>setDocument(document);setVisibleRegion(offset, length)</code>.
306: *
307: * @param document the new input document or <code>null</code> if none
308: * @param modelRangeOffset the offset of the model range
309: * @param modelRangeLength the length of the model range
310: */
311: void setDocument(IDocument document, int modelRangeOffset,
312: int modelRangeLength);
313:
314: /**
315: * Defines and sets the region of this viewer's document which will be
316: * visible in the presentation. Every character inside the specified region
317: * is supposed to be visible in the viewer's widget after that call.
318: *
319: * @param offset the offset of the visible region
320: * @param length the length of the visible region
321: */
322: void setVisibleRegion(int offset, int length);
323:
324: /**
325: * Resets the region of this viewer's document which is visible in the presentation.
326: * Afterwards, the whole input document is visible.
327: */
328: void resetVisibleRegion();
329:
330: /**
331: * Returns the current visible region of this viewer's document. The result
332: * may differ from the argument passed to <code>setVisibleRegion</code> if
333: * the document has been modified since then. The visible region is supposed
334: * to be a consecutive region in viewer's input document and every character
335: * inside that region is supposed to visible in the viewer's widget.
336: * <p>
337: * Viewers implementing {@link ITextViewerExtension5} may be forced to
338: * change the fractions of the input document that are shown, in order to
339: * fulfill this contract.
340: *
341: * @return this viewer's current visible region
342: */
343: IRegion getVisibleRegion();
344:
345: /**
346: * Returns whether a given range overlaps with the visible region of this
347: * viewer's document.
348: * <p>
349: * Viewers implementing {@link ITextViewerExtension5}may be forced to
350: * change the fractions of the input document that are shown in order to
351: * fulfill this request. This is because the overlap is supposed to be
352: * without gaps.
353: *
354: * @param offset the offset
355: * @param length the length
356: * @return <code>true</code> if the specified range overlaps with the
357: * visible region
358: */
359: boolean overlapsWithVisibleRegion(int offset, int length);
360:
361: /* ------------- presentation manipulation ----------- */
362:
363: /**
364: * Applies the color information encoded in the given text presentation.
365: * <code>controlRedraw</code> tells this viewer whether it should take care of
366: * redraw management or not. If, e.g., this call is one in a sequence of multiple
367: * presentation calls, it is more appropriate to explicitly control redrawing at the
368: * beginning and the end of the sequence.
369: *
370: * @param presentation the presentation to be applied to this viewer
371: * @param controlRedraw indicates whether this viewer should manage redraws
372: */
373: void changeTextPresentation(TextPresentation presentation,
374: boolean controlRedraw);
375:
376: /**
377: * Marks the currently applied text presentation as invalid. It is the
378: * viewer's responsibility to take any action it can to repair the text
379: * presentation.
380: * <p>
381: * See {@link ITextViewerExtension2#invalidateTextPresentation(int, int)}
382: * for a way to invalidate specific regions rather than the presentation as
383: * a whole.
384: *
385: * @since 2.0
386: */
387: void invalidateTextPresentation();
388:
389: /**
390: * Applies the given color as text foreground color to this viewer's
391: * selection.
392: *
393: * @param color the color to be applied
394: */
395: void setTextColor(Color color);
396:
397: /**
398: * Applies the given color as text foreground color to the specified section
399: * of this viewer. <code>controlRedraw</code> tells this viewer whether it
400: * should take care of redraw management or not.
401: *
402: * @param color the color to be applied
403: * @param offset the offset of the range to be changed
404: * @param length the length of the range to be changed
405: * @param controlRedraw indicates whether this viewer should manage redraws
406: */
407: void setTextColor(Color color, int offset, int length,
408: boolean controlRedraw);
409:
410: /* --------- target handling and configuration ------------ */
411:
412: /**
413: * Returns the text operation target of this viewer.
414: *
415: * @return the text operation target of this viewer
416: */
417: ITextOperationTarget getTextOperationTarget();
418:
419: /**
420: * Returns the find/replace operation target of this viewer.
421: *
422: * @return the find/replace operation target of this viewer
423: */
424: IFindReplaceTarget getFindReplaceTarget();
425:
426: /**
427: * Sets the strings that are used as prefixes when lines of the given content type
428: * are prefixed using the prefix text operation. The prefixes are considered equivalent.
429: * Inserting a prefix always inserts the defaultPrefixes[0].
430: * Removing a prefix removes all of the specified prefixes.
431: *
432: * @param defaultPrefixes the prefixes to be used
433: * @param contentType the content type for which the prefixes are specified
434: * @since 2.0
435: */
436: void setDefaultPrefixes(String[] defaultPrefixes, String contentType);
437:
438: /**
439: * Sets the strings that are used as prefixes when lines of the given content type
440: * are shifted using the shift text operation. The prefixes are considered equivalent.
441: * Thus "\t" and " " can both be used as prefix characters.
442: * Shift right always inserts the indentPrefixes[0].
443: * Shift left removes all of the specified prefixes.
444: *
445: * @param indentPrefixes the prefixes to be used
446: * @param contentType the content type for which the prefixes are specified
447: */
448: void setIndentPrefixes(String[] indentPrefixes, String contentType);
449:
450: /* --------- selection handling -------------- */
451:
452: /**
453: * Sets the selection to the specified range.
454: *
455: * @param offset the offset of the selection range
456: * @param length the length of the selection range
457: */
458: void setSelectedRange(int offset, int length);
459:
460: /**
461: * Returns the range of the current selection in coordinates of this viewer's document.
462: *
463: * @return a <code>Point</code> with x as the offset and y as the length of the current selection
464: */
465: Point getSelectedRange();
466:
467: /**
468: * Returns a selection provider dedicated to this viewer. Subsequent
469: * calls to this method return always the same selection provider.
470: *
471: * @return this viewer's selection provider
472: */
473: ISelectionProvider getSelectionProvider();
474:
475: /* ------------- appearance manipulation --------------- */
476:
477: /**
478: * Ensures that the given range is visible.
479: *
480: * @param offset the offset of the range to be revealed
481: * @param length the length of the range to be revealed
482: */
483: void revealRange(int offset, int length);
484:
485: /**
486: * Scrolls the widget so that the given index is the line
487: * with the smallest line number of all visible lines.
488: *
489: * @param index the line which should become the top most line
490: */
491: void setTopIndex(int index);
492:
493: /**
494: * Returns the visible line with the smallest line number.
495: *
496: * @return the number of the top most visible line
497: */
498: int getTopIndex();
499:
500: /**
501: * Returns the document offset of the upper left corner of this viewer's view port.
502: *
503: * @return the upper left corner offset
504: */
505: int getTopIndexStartOffset();
506:
507: /**
508: * Returns the visible line with the highest line number.
509: *
510: * @return the number of the bottom most line
511: */
512: int getBottomIndex();
513:
514: /**
515: * Returns the document offset of the lower right
516: * corner of this viewer's view port. This is the visible character
517: * with the highest character position. If the content of this viewer
518: * is shorter, the position of the last character of the content is returned.
519: *
520: * @return the lower right corner offset
521: */
522: int getBottomIndexEndOffset();
523:
524: /**
525: * Returns the vertical offset of the first visible line.
526: *
527: * @return the vertical offset of the first visible line
528: */
529: int getTopInset();
530: }
|