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.