org.eclipse.jface.text
Interface ITextViewer

All Known Subinterfaces:

ISourceViewer

All Known Implementing Classes:

SourceViewer, TextViewer

public interface ITextViewer

A text viewer turns a text widget into a document-based text widget. It supports the following kinds of listeners:

• viewport listeners to inform about changes of the viewer's viewport
• text listeners to inform about changes of the document and the subsequent viewer change
• text input listeners to inform about changes of the viewer's input document.

A text viewer supports a set of plug-ins which define its behavior:

• undo manager
• double click behavior
• auto indentation
• text hover

Installed plug-ins are not automatically activated. Plug-ins must be activated with the activatePlugins call. Most plug-ins can be defined per content type. Content types are derived from the partitioning of the text viewer's input document.

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.

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 specified sections of its document. The viewer's presentation mode does not affect any client of the viewer other than text listeners.

Clients may implement this interface or use the standard implementation TextViewer.

See Also:

IDocument, ITextInputListener, IViewportListener, ITextListener, IEventConsumer

Method Summary

void	activatePlugins() Activates the installed plug-ins.
void	addTextInputListener(ITextInputListener listener) Adds a text input listener to this viewer.
void	addTextListener(ITextListener listener) Adds a text listener to this viewer.
void	addViewportListener(IViewportListener listener) Adds the given viewport listener to this viewer.
void	changeTextPresentation(TextPresentation presentation, boolean controlRedraw) Applies the color information encoded in the given text presentation.
int	getBottomIndex() Returns the visible line with the highest line number.
int	getBottomIndexEndOffset() Returns the document offset of the lower right corner of this viewer's viewport.
IDocument	getDocument() Returns the text viewer's input document.
IFindReplaceTarget	getFindReplaceTarget() Returns the find/replace operation target of this viewer.
Point	getSelectedRange() Returns the range of the current selection in coordinates of this viewer's document.
ISelectionProvider	getSelectionProvider() Returns a selection provider dedicated to this viewer.
ITextOperationTarget	getTextOperationTarget() Returns the text operation target of this viewer.
StyledText	getTextWidget() Returns this viewer's SWT control, null if the control is disposed.
int	getTopIndex() Returns the visible line with the smallest line number.
int	getTopIndexStartOffset() Returns the document offset of the upper left corner of this viewer's viewport.
int	getTopInset() Returns the vertical offset of the first visible line.
IRegion	getVisibleRegion() Returns the current visible region of this viewer's document.
void	invalidateTextPresentation() Marks the currently applied text presentation as invalid.
boolean	isEditable() Returns whether the shown text can be manipulated.
boolean	overlapsWithVisibleRegion(int offset, int length) Returns whether a given range overlaps with the visible region of this viewer's document.
void	removeTextInputListener(ITextInputListener listener) Removes the given listener from this viewer's set of text input listeners.
void	removeTextListener(ITextListener listener) Removes the given listener from this viewer's set of text listeners.
void	removeViewportListener(IViewportListener listener) Removes the given listener from this viewer's set of viewport listeners.
void	resetPlugins() Resets the installed plug-ins.
void	resetVisibleRegion() Resets the region of this viewer's document which is visible in the presentation.
void	revealRange(int offset, int length) Ensures that the given range is visible.
void	setAutoIndentStrategy(IAutoIndentStrategy strategy, String contentType) Sets this viewer's auto indent strategy for the given content type.
void	setDefaultPrefixes(String[] defaultPrefixes, String contentType) Sets the string that is used as prefix when lines of the given content type are prefixed by the prefix text operation.
void	setDocument(IDocument document) Sets the given document as the text viewer's model and updates the presentation accordingly.
void	setDocument(IDocument document, int visibleRegionOffset, int visibleRegionLength) Sets the given document as this viewer's model and makes the specified region visible in the presentation.
void	setEditable(boolean editable) Sets the editable mode.
void	setEventConsumer(IEventConsumer consumer) Registers an event consumer with this viewer.
void	setIndentPrefixes(String[] indentPrefixes, String contentType) Sets the strings that are used as prefixes when lines of the given content type are shifted using the shift text operation.
void	setSelectedRange(int offset, int length) Sets the selection to the specified range.
void	setTextColor(Color color) Applies the given color to this viewer's selection.
void	setTextColor(Color color, int offset, int length, boolean controlRedraw) Applies the given color to the specified section of this viewer.
void	setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy, String contentType) Sets this viewer's text double click strategy for the given content type.
void	setTextHover(ITextHover textViewerHover, String contentType) Sets this viewer's text hover for the given content type.
void	setTopIndex(int index) Scrolls the widget so the the given index is the line with the smallest line number of all visible lines.
void	setUndoManager(IUndoManager undoManager) Sets this viewer's undo manager.
void	setVisibleRegion(int offset, int length) Sets the region of this viewer's document which will be visible in the presentation.

Method Detail

getTextWidget

public StyledText getTextWidget()

Returns this viewer's SWT control, null if the control is disposed.

Returns:

the SWT control

setUndoManager

public void setUndoManager(IUndoManager undoManager)

Sets this viewer's undo manager.

Parameters:

undoManager - the new undo manager. null is a valid argument.

setTextDoubleClickStrategy

public void setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy,
                                       String contentType)

Sets this viewer's text double click strategy for the given content type.

Parameters:

strategy - the new double click strategy. null is a valid argument.

contentType - the type for which the strategy is registered

setAutoIndentStrategy

public void setAutoIndentStrategy(IAutoIndentStrategy strategy,
                                  String contentType)

Sets this viewer's auto indent strategy for the given content type.

Parameters:

strategy - the new auto indent strategy. null is a valid argument.

contentType - the type for which the strategy is registered

setTextHover

public void setTextHover(ITextHover textViewerHover,
                         String contentType)

Sets this viewer's text hover for the given content type.

Parameters:

textViewerHover - the new hover. null is a valid argument.

contentType - the type for which the hover is registered

activatePlugins

public void activatePlugins()

Activates the installed plug-ins. If the plug-ins are already activated this call has no effect.

resetPlugins

public void resetPlugins()

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 IUndoManager has been installed on this text viewer, the manager's list of remembered text editing operations is removed.

addViewportListener

public void addViewportListener(IViewportListener listener)

Adds the given viewport listener to this viewer. The listener is informed about all changes to the visible area of this viewer. If the listener is already registered with this viewer, this call has no effect.

Parameters:

listener - the listener to be added

removeViewportListener

public void removeViewportListener(IViewportListener listener)

Removes the given listener from this viewer's set of viewport listeners. If the listener is not registered with this viewer, this call has no effect.

Parameters:

listener - the listener to be removed

addTextListener

public void addTextListener(ITextListener listener)

Adds a text listener to this viewer. If the listener is already registered with this viewer, this call has no effect.

Parameters:

listener - the listener to be added

removeTextListener

public void removeTextListener(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.

Parameters:

listener - the listener to be removed

addTextInputListener

public void addTextInputListener(ITextInputListener listener)

Adds a text input listener to this viewer. If the listener is already registered with this viewer, this call has no effect.

Parameters:

listener - the listener to be added

removeTextInputListener

public void removeTextInputListener(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.

Parameters:

listener - the listener to be removed

setDocument

public void setDocument(IDocument document)

Sets the given document as the text viewer's model and updates the presentation accordingly. An approriate TextEvent is issued. This text event does not carry a related document event.

Parameters:

document - the viewer's new input document

getDocument

public IDocument getDocument()

Returns the text viewer's input document.

Returns:

the viewer's input document

setEventConsumer

public void setEventConsumer(IEventConsumer consumer)

Registers an event consumer with this viewer.

Parameters:

consumer - the viewer's event consumer. null is a valid argument.

setEditable

public void setEditable(boolean editable)

Sets the editable mode.

Parameters:

editable - the editable mode

isEditable

public boolean isEditable()

Returns whether the shown text can be manipulated.

Returns:

the viewer's editable mode

setDocument

public void setDocument(IDocument document,
                        int visibleRegionOffset,
                        int visibleRegionLength)

Sets the given document as this viewer's model and makes the specified region visible in the presentation. An approriate TextEvent is issued. The text event does not carry a related document event. This method is a convenience method for setDocument(document);setVisibleRegion(offset, length).

Parameters:

document - the new input document

visibleRegionOffset - the offset of the visible region

visibleRegionLength - the length of the visible region

setVisibleRegion

public void setVisibleRegion(int offset,
                             int length)

Sets the region of this viewer's document which will be visible in the presentation.

Parameters:

offset - the offset of the visible region

length - the length of the visible region

resetVisibleRegion

public void resetVisibleRegion()

Resets the region of this viewer's document which is visible in the presentation. Afterwards, the whole document is presented again.

getVisibleRegion

public IRegion getVisibleRegion()

Returns the current visible region of this viewer's document. The result may differ from the argument passed to setVisibleRegion if the document has been modified since then.

Returns:

this viewer's current visible region

overlapsWithVisibleRegion

public boolean overlapsWithVisibleRegion(int offset,
                                         int length)

Returns whether a given range overlaps with the visible region of this viewer's document.

Returns:

true if the specified range overlaps with the visible region

changeTextPresentation

public void changeTextPresentation(TextPresentation presentation,
                                   boolean controlRedraw)

Applies the color information encoded in the given text presentation. controlRedraw 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 coloring calls, it is more appropriate to explicitly control redrawing at the beginning and the end of the sequence.

Parameters:

presentation - the presentation to be applied to this viewer

controlRedraw - indicates whether this viewer should manage redraws

invalidateTextPresentation

public void invalidateTextPresentation()

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.

Since:

2.0

setTextColor

public void setTextColor(Color color)

Applies the given color to this viewer's selection.

Parameters:

color - the color to be applied

setTextColor

public void setTextColor(Color color,
                         int offset,
                         int length,
                         boolean controlRedraw)

Applies the given color to the specified section of this viewer. controlRedraw tells this viewer whether it should take care of redraw management or not.

Parameters:

color - the color to be applied

offset - the offset of the range to be colored

length - the length of the range to be colored

controlRedraw - indicates whether this viewer should manage redraws

getTextOperationTarget

public ITextOperationTarget getTextOperationTarget()

Returns the text operation target of this viewer.

Returns:

the text operation target of this viewer

getFindReplaceTarget

public IFindReplaceTarget getFindReplaceTarget()

Returns the find/replace operation target of this viewer.

Returns:

the find/replace operation target of this viewer

setDefaultPrefixes

public void setDefaultPrefixes(String[] defaultPrefixes,
                               String contentType)

Sets the string that is used as prefix when lines of the given content type are prefixed by the prefix text operation. 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.

Parameters:

defaultPrefixes - the prefixes to be used

contentType - the content type for which the prefixes are specified

Since:

2.0

setIndentPrefixes

public void setIndentPrefixes(String[] indentPrefixes,
                              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.

Parameters:

indentPrefixes - the prefixes to be used

contentType - the content type for which the prefixes are specified

setSelectedRange

public void setSelectedRange(int offset,
                             int length)

Sets the selection to the specified range.

Parameters:

offset - the offset of the selection range

length - the length of the selection range

getSelectedRange

public Point getSelectedRange()

Returns the range of the current selection in coordinates of this viewer's document.

Returns:

the current selection

getSelectionProvider

public ISelectionProvider getSelectionProvider()

Returns a selection provider dedicated to this viewer. Subsequent calls to this method return always the same selection provider.

Returns:

this viewer's selection provider

revealRange

public void revealRange(int offset,
                        int length)

Ensures that the given range is visible.

Parameters:

offset - the offset of the range to be revealed

length - the length of the range to be revealed

setTopIndex

public void setTopIndex(int index)

Scrolls the widget so the the given index is the line with the smallest line number of all visible lines.

Parameters:

index - the line which should become the top most line

getTopIndex

public int getTopIndex()

Returns the visible line with the smallest line number.

Returns:

the number of the top most visible line

getTopIndexStartOffset

public int getTopIndexStartOffset()

Returns the document offset of the upper left corner of this viewer's viewport.

Returns:

the upper left corner offset

getBottomIndex

public int getBottomIndex()

Returns the visible line with the highest line number.

Returns:

the number of the bottom most line

getBottomIndexEndOffset

public int getBottomIndexEndOffset()

Returns the document offset of the lower right corner of this viewer's viewport. 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.

Returns:

the lower right corner offset

getTopInset

public int getTopInset()

Returns the vertical offset of the first visible line.

Returns:

the vertical offset of the first visible line