Text and ruler hover
Hover support is provided in the platform text framework, allowing you to implement
informational hovers (or infopops) over the text and the rulers shown in your
editor.
Hover support is optional. By default,
SourceViewerConfiguration
does not install hover behavior since there is no useful general information
to show. In order to provide text or ruler hover, your editor's source
viewer configuration must be
configured
to define a pluggable hover object.
Let's look again at JavaSourceViewerConfiguration
to see which methods define the hover behavior:
public ITextHover getTextHover(ISourceViewer sourceViewer, String contentType) {
return new JavaTextHover();
}
public IAnnotationHover getAnnotationHover(ISourceViewer sourceViewer) {
return new JavaAnnotationHover();
}
Hover helper classes can also be installed dynamically using
SourceViewer
protocol (setTextHover and setAnnotationHover). There is no
particular runtime benefit to doing it either way, but putting all of the
pluggable behavior overrides in a subclass of
SourceViewerConfiguration
provides the advantage of consolidating all of the definitions in one place.
Let's look at the specifics of providing both kinds of hover.
Text hover
Text hover allows you to provide informational text about text shown in the
editor. This is done using the
ITextHover
interface. A text hover is responsible for computing the region that should
be used as the source of hover information, given an offset into the document.
It is also responsible for providing the informational text about a specific
region. JavaTextHover is pretty simple. It checks to see
if the supplied offset for hover is contained inside the text selection.
If so, it supplies the selection range as hover region.
public class JavaTextHover implements ITextHover {
...
public IRegion getHoverRegion(ITextViewer textViewer, int offset) {
Point selection= textViewer.getSelectedRange();
if (selection.x <= offset && offset < selection.x + selection.y)
return new Region(selection.x, selection.y);
return new Region(offset, 0);
}
}
Given its own computed hover region, it obtains the selected text from its
document and returns that as the hover info.
public class JavaTextHover implements ITextHover {
public String getHoverInfo(ITextViewer textViewer, IRegion hoverRegion) {
if (hoverRegion != null) {
try {
if (hoverRegion.getLength() > -1)
return textViewer.getDocument().get(hoverRegion.getOffset(), hoverRegion.getLength());
} catch (BadLocationException x) {
}
}
return JavaEditorMessages.getString("JavaTextHover.emptySelection");
}
...
}
Sure enough, we can see that if we hover over a selection in the editor, the
hover text shows the selection.
More complicated contextual information can be used to compute useful hover
information. Examples of this can be found in the JavaTextHover
implemented with the JDT editor.
Ruler hover
Hover on the vertical ruler is useful for showing show line-oriented information.
The hover class is configured as described above.
IAnnotationHover
is the interface for ruler hover objects. Although the name implies that
the hover is designed for annotations in the ruler, it is really up to an
individual editor to detemine what is appropriate. A ruler hover is responsible for returning the info string associated with a
particular line number, regardless of the presence of markers on that line.
The Java example editor's JavaAnnotationHover implements hover for
all lines. It uses the line number to
obtain all of the text on the hover line and returning it as the info string.
public String getHoverInfo(ISourceViewer sourceViewer, int lineNumber) {
IDocument document= sourceViewer.getDocument();
try {
IRegion info= document.getLineInformation(lineNumber);
return document.get(info.getOffset(), info.getLength());
} catch (BadLocationException x) {
}
return null;
}
Since the hover has access to the document and the
source viewer, it has all the context needed to make more complicated contextual
decisions about the info that should be shown. For example, the annotation
model could be retrieved from the source viewer in order to provide hover info
for any annotations shown in the vertical ruler. The JavaAnnotationHover
provided by the JDT editor provides this capability.
