/*******************************************************************************
* 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
*/
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();
}