org.eclipse.jface.text
Interface ITextViewer
-
All Known Subinterfaces:
-
ISourceViewer
-
All Known Implementing Classes:
-
ProjectionViewer,
SourceViewer,
TextConsoleViewer,
TextViewer
-
public interface ITextViewer
A text viewer connects a text widget with an
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.
A text viewer supports a set of configuration options and plug-ins defining
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 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 behavior
-
ITextViewerExtension2since 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 by
ITextViewerExtension5 in version 3.0
-
ITextViewerExtension4 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.
-
See Also:
-
ITextViewerExtension,
ITextViewerExtension2,
ITextViewerExtension3,
ITextViewerExtension4,
ITextViewerExtension5,
ITextViewerExtension6,
ITextViewerExtension7,
ITextViewerExtension8,
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 view port 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 view port. |
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 view port. |
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 view port 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)
Deprecated. since 3.1, use
ITextViewerExtension2.prependAutoEditStrategy(IAutoEditStrategy, String) and
ITextViewerExtension2.removeAutoEditStrategy(IAutoEditStrategy, String) instead
|
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. |
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
void setUndoManager(
IUndoManager undoManager)
- Sets this viewer's undo manager.
-
-
Parameters:
-
undoManager - the new undo manager. null is a valid argument.
setTextDoubleClickStrategy
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
void setAutoIndentStrategy(
IAutoIndentStrategy strategy,
String contentType)
-
Deprecated. since 3.1, use
ITextViewerExtension2.prependAutoEditStrategy(IAutoEditStrategy, String) and
ITextViewerExtension2.removeAutoEditStrategy(IAutoEditStrategy, String) instead
- Sets this viewer's auto indent strategy for the given content type. If
the given strategy is
null any installed strategy for the
content type is removed. This method has been replaced by
ITextViewerExtension2.prependAutoEditStrategy(IAutoEditStrategy, String) and
ITextViewerExtension2.removeAutoEditStrategy(IAutoEditStrategy, String).
It is now equivalent to
ITextViewerExtension2 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
void setTextHover(
ITextHover textViewerHover,
String contentType)
- 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 to
ITextViewerExtension2 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 an
IUndoManager
has been installed on this text viewer, the manager's list of remembered
text editing operations is removed.
-
addViewportListener
void addViewportListener(
IViewportListener listener)
- 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
void removeViewportListener(
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.
-
-
Parameters:
-
listener - the listener to be removed
addTextListener
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
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
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
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
void setDocument(
IDocument document)
- Sets the given document as the text viewer's model and updates the
presentation accordingly. An appropriate
TextEvent is
issued. This text event does not carry a related document event.
-
-
Parameters:
-
document - the viewer's new input document null if none
getDocument
IDocument getDocument()
- Returns the text viewer's input document.
-
-
Returns:
- the viewer's input document or
null if none
setEventConsumer
void setEventConsumer(
IEventConsumer consumer)
- Registers an event consumer with this viewer. This method has been
replaces with the
VerifyKeyListener
management methods in
ITextViewerExtension.
-
-
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
void setDocument(
IDocument document,
int modelRangeOffset,
int modelRangeLength)
- Sets the given document as this viewer's model and
exposes the specified region. An appropriate
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 or null if none -
modelRangeOffset - the offset of the model range -
modelRangeLength - 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 region -
length - 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 to
setVisibleRegion 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
ITextViewerExtension5may 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 offset -
length - the length
-
Returns:
-
true if the specified range overlaps with the
visible region
changeTextPresentation
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
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 viewer -
controlRedraw - 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
void setTextColor(
Color color)
- Applies the given color as text foreground color to this viewer's
selection.
-
-
Parameters:
-
color - the color to be applied
setTextColor
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.
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 changed -
length - the length of the range to be changed -
controlRedraw - 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
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. 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
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
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. 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 revealed -
length - 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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
