Interface ITextViewer
- All Known Subinterfaces:
ISourceViewer
- All Known Implementing Classes:
ProjectionViewer
,SourceViewer
,TextConsoleViewer
,TextViewer
IDocument
. The
document is used as the widget's text model.
It supports the following kinds of listeners:
- view port listeners to inform about changes of the viewer's view port
- 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.
- 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 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.
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
ITextViewerExtension
, this mechanism has been replaced with the
support for VerifyKeyListener
.
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 setVisibleRegion
clients define which
section is visible. Clients can get access to this section by calling
getVisibleRegion
. The viewer's presentation mode does not affect any client of the
viewer other than text listeners. With 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 ITextViewerExtension5
are
potentially forced to change the fractions of the input document that are shown when clients ask
for the visible region.
In order to provide backward compatibility for clients of ITextViewer
, extension
interfaces are used as a means of evolution. The following extension interfaces exist:
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 behaviorITextViewerExtension2
since version 2.1 adding a way to invalidate a viewer's presentation and setters for hovers.ITextViewerExtension3
since version 2.1 which itself was replaced byITextViewerExtension5
in version 3.0ITextViewerExtension4
since version 3.0 introducing focus handling for widget token keepers and the concept of text presentation listeners.ITextViewerExtension5
since version 3.0 extending the visible region concept with explicit handling and conversion of widget and model coordinates.ITextViewerExtension6
since version 3.1 extending the text viewer with the ability to detect hyperlinks and access the undo manager.ITextViewerExtension7
since version 3.3 extending the text viewer with the ability to install tabs to spaces conversion.ITextViewerExtension8
since version 3.4 extending the text viewer with the ability to print and rich hover support.
Clients may implement this interface and its extension interfaces or use the standard
implementation TextViewer
.
-
Method Summary
Modifier and TypeMethodDescriptionvoid
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 view port listener to this viewer.void
changeTextPresentation
(TextPresentation presentation, boolean controlRedraw) Applies the color information encoded in the given text presentation.int
Returns the visible line with the highest line number.int
Returns the document offset of the lower right corner of this viewer's view port.Returns the text viewer's input document.Returns the find/replace operation target of this viewer.Returns the range of the current selection in coordinates of this viewer's document.Returns a selection provider dedicated to this viewer.Returns the text operation target of this viewer.Returns this viewer's SWT control,null
if the control is disposed.int
Returns the visible line with the smallest line number.int
Returns the document offset of the upper left corner of this viewer's view port.int
Returns the vertical offset of the first visible line.Returns the current visible region of this viewer's document.void
Marks the currently applied text presentation as invalid.boolean
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 view port listeners.void
Resets the installed plug-ins.void
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) Deprecated.void
setDefaultPrefixes
(String[] defaultPrefixes, String contentType) Sets the strings that are used as prefixes when lines of the given content type are prefixed using 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 modelRangeOffset, int modelRangeLength) Sets the given document as this viewer's model and exposes the specified region.void
setEditable
(boolean editable) Sets the editable state.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 as text foreground color to this viewer's selection.void
setTextColor
(Color color, int offset, int length, boolean controlRedraw) Applies the given color as text foreground 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 that 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) Defines and sets the region of this viewer's document which will be visible in the presentation.
-
Method Details
-
getTextWidget
StyledText getTextWidget()Returns this viewer's SWT control,null
if the control is disposed.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.
- Returns:
- the SWT control or
null
-
setUndoManager
Sets this viewer's undo manager.- Parameters:
undoManager
- the new undo manager.null
is a valid argument.
-
setTextDoubleClickStrategy
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
Deprecated.Sets this viewer's auto indent strategy for the given content type. If the given strategy isnull
any installed strategy for the content type is removed. This method has been replaced byITextViewerExtension2.prependAutoEditStrategy(IAutoEditStrategy, String)
andITextViewerExtension2.removeAutoEditStrategy(IAutoEditStrategy, String)
. It is now equivalent toITextViewerExtension2 extension= (ITextViewerExtension2) viewer; extension.removeAutoEditStrategy(oldStrategy, contentType); extension.prependAutoEditStrategy(strategy, contentType);
- Parameters:
strategy
- the new auto indent strategy.null
is a valid argument.contentType
- the type for which the strategy is registered
-
setTextHover
Sets this viewer's text hover for the given content type.This method has been replaced by
ITextViewerExtension2.setTextHover(ITextHover, String, int)
. It is now equivalent toITextViewerExtension2 extension= (ITextViewerExtension2) document; extension.setTextHover(textViewerHover, contentType, ITextViewerExtension2#DEFAULT_HOVER_STATE_MASK);
- Parameters:
textViewerHover
- the new hover.null
is a valid argument.contentType
- the type for which the hover is registered
-
activatePlugins
void activatePlugins()Activates the installed plug-ins. If the plug-ins are already activated this call has no effect. -
resetPlugins
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 anIUndoManager
has been installed on this text viewer, the manager's list of remembered text editing operations is removed. -
addViewportListener
Adds the given view port 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
-
removeViewportListener
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.- Parameters:
listener
- the listener to be removed
-
addTextListener
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
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
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
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
Sets the given document as the text viewer's model and updates the presentation accordingly. An appropriateTextEvent
is issued. This text event does not carry a related document event.- Parameters:
document
- the viewer's new input documentnull
if none
-
getDocument
IDocument getDocument()Returns the text viewer's input document.- Returns:
- the viewer's input document or
null
if none
-
setEventConsumer
Registers an event consumer with this viewer. This method has been replaces with theVerifyKeyListener
management methods inITextViewerExtension
.- Parameters:
consumer
- the viewer's event consumer.null
is a valid argument.
-
setEditable
void setEditable(boolean editable) Sets the editable state.- Parameters:
editable
- the editable state
-
isEditable
boolean isEditable()Returns whether the shown text can be manipulated.- Returns:
- the viewer's editable state
-
setDocument
Sets the given document as this viewer's model and exposes the specified region. An appropriateTextEvent
is issued. The text event does not carry a related document event. This method is a convenience method forsetDocument(document);setVisibleRegion(offset, length)
.- Parameters:
document
- the new input document ornull
if nonemodelRangeOffset
- the offset of the model rangemodelRangeLength
- the length of the model range
-
setVisibleRegion
void setVisibleRegion(int offset, int length) 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.- Parameters:
offset
- the offset of the visible regionlength
- the length of the visible region
-
resetVisibleRegion
void resetVisibleRegion()Resets the region of this viewer's document which is visible in the presentation. Afterwards, the whole input document is visible. -
getVisibleRegion
IRegion getVisibleRegion()Returns the current visible region of this viewer's document. The result may differ from the argument passed tosetVisibleRegion
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.Viewers implementing
ITextViewerExtension5
may be forced to change the fractions of the input document that are shown, in order to fulfill this contract.- Returns:
- this viewer's current visible region
-
overlapsWithVisibleRegion
boolean overlapsWithVisibleRegion(int offset, int length) Returns whether a given range overlaps with the visible region of this viewer's document.Viewers implementing
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.- Parameters:
offset
- the offsetlength
- the length- Returns:
true
if the specified range overlaps with the visible region
-
changeTextPresentation
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 presentation 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 viewercontrolRedraw
- indicates whether this viewer should manage redraws
-
invalidateTextPresentation
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.See
ITextViewerExtension2.invalidateTextPresentation(int, int)
for a way to invalidate specific regions rather than the presentation as a whole.- Since:
- 2.0
-
setTextColor
Applies the given color as text foreground color to this viewer's selection.- Parameters:
color
- the color to be applied
-
setTextColor
Applies the given color as text foreground 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 appliedoffset
- the offset of the range to be changedlength
- the length of the range to be changedcontrolRedraw
- indicates whether this viewer should manage redraws
-
getTextOperationTarget
ITextOperationTarget getTextOperationTarget()Returns the text operation target of this viewer.- Returns:
- the text operation target of this viewer
-
getFindReplaceTarget
IFindReplaceTarget getFindReplaceTarget()Returns the find/replace operation target of this viewer.- Returns:
- the find/replace operation target of this viewer
-
setDefaultPrefixes
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 usedcontentType
- the content type for which the prefixes are specified- Since:
- 2.0
-
setIndentPrefixes
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 usedcontentType
- the content type for which the prefixes are specified
-
setSelectedRange
void setSelectedRange(int offset, int length) Sets the selection to the specified range.- Parameters:
offset
- the offset of the selection rangelength
- the length of the selection range. A negative length places the caret at the visual start of the selection.
-
getSelectedRange
Point getSelectedRange()Returns the range of the current selection in coordinates of this viewer's document.- Returns:
- a
Point
with x as the offset and y as the length of the current selection
-
getSelectionProvider
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
void revealRange(int offset, int length) Ensures that the given range is visible.- Parameters:
offset
- the offset of the range to be revealedlength
- the length of the range to be revealed
-
setTopIndex
void setTopIndex(int index) Scrolls the widget so that 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
int getTopIndex()Returns the visible line with the smallest line number.- Returns:
- the number of the top most visible line
-
getTopIndexStartOffset
int getTopIndexStartOffset()Returns the document offset of the upper left corner of this viewer's view port.- Returns:
- the upper left corner offset
-
getBottomIndex
int getBottomIndex()Returns the visible line with the highest line number.- Returns:
- the number of the bottom most line
-
getBottomIndexEndOffset
int getBottomIndexEndOffset()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.- Returns:
- the lower right corner offset
-
getTopInset
int getTopInset()Returns the vertical offset of the first visible line.- Returns:
- the vertical offset of the first visible line
-
ITextViewerExtension2.prependAutoEditStrategy(IAutoEditStrategy, String)
andITextViewerExtension2.removeAutoEditStrategy(IAutoEditStrategy, String)
instead