bundles/org.eclipse.platform.doc.isv/guide/editors_hover.htm - gerrit/platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
 <HEAD>

 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

 <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
 <TITLE>
 Text and ruler hover
 </TITLE>

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <H2>Text and ruler hover</H2>
 <p>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.</p>
 <p>Hover support is optional.&nbsp; By default, <b><a href="../reference/api/org/eclipse/jface/text/source/SourceViewerConfiguration.html">SourceViewerConfiguration</a>
 </b>does not install hover behavior since there is no useful general information
 to show.&nbsp; In order to provide text or ruler hover, your editor's source
 viewer configuration must be <a href="editors_sourceviewers.htm">configured</a>
 to define a pluggable hover object.</p>
 <p>Let's look again at <b>JavaSourceViewerConfiguration</b>
  to see which methods define the hover behavior:</p>

 <pre>public ITextHover getTextHover(ISourceViewer sourceViewer, String contentType) {
 	return new JavaTextHover();
 }
 public IAnnotationHover getAnnotationHover(ISourceViewer sourceViewer) {
 	return new JavaAnnotationHover();
 }
 </pre>
 <p>Hover helper classes can also be installed dynamically using <b><a href="../reference/api/org/eclipse/jface/text/source/SourceViewer.html">SourceViewer</a></b>
  protocol (<b>setTextHover</b> and <b>setAnnotationHover</b>).&nbsp; There is no
 particular runtime benefit to doing it either way, but putting all of the
 pluggable behavior overrides in a subclass of <b><a href="../reference/api/org/eclipse/jface/text/source/SourceViewerConfiguration.html">SourceViewerConfiguration</a>
 </b>provides the advantage of consolidating all of the definitions in one place.</p>
 <p>Let's look at the specifics of providing both kinds of hover.</p>
 <h3>Text hover</h3>
 <p>Text hover allows you to provide informational text about text shown in the
   editor.&nbsp; This is done using the <b><a href="../reference/api/org/eclipse/jface/text/ITextHover.html">ITextHover</a></b>
   interface.&nbsp; 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.&nbsp;
   It is also responsible for providing the informational text about a specific
   region.&nbsp; <b>JavaTextHover</b> is pretty simple.&nbsp; It checks to see
   if the supplied offset for hover is contained inside the text selection.&nbsp;&nbsp;&nbsp;
   If so, it supplies the selection range as hover region.&nbsp;</p>

 <pre>public class JavaTextHover implements ITextHover {

 	...

 	public IRegion getHoverRegion(ITextViewer textViewer, int offset) {
 		Point selection= textViewer.getSelectedRange();
 		if (selection.x &lt;= offset &amp;&amp; offset &lt; selection.x + selection.y)
 			return new Region(selection.x, selection.y);
 		return new Region(offset, 0);
 	}
 }</pre>
 <p>Given its own computed hover region, it obtains the selected text from its
 document and returns that as the hover info.</p>

 <pre>public class JavaTextHover implements ITextHover {

 	public String getHoverInfo(ITextViewer textViewer, IRegion hoverRegion) {
 		if (hoverRegion != null) {
 			try {
 				if (hoverRegion.getLength() &gt; -1)
 					return textViewer.getDocument().get(hoverRegion.getOffset(), hoverRegion.getLength());
 			} catch (BadLocationException x) {
 			}
 		}
 		return JavaEditorMessages.getString(&quot;JavaTextHover.emptySelection&quot;);
 	}
 	...
 }</pre>
 <p>Sure enough, we can see that if we hover over a selection in the editor, the
 hover text shows the selection.</p>
 <p><img src="images/javatexthover.png" alt="Hover information on selected region" border="0"></p>
 <p>More complicated contextual information can be used to compute useful hover
 information.&nbsp; Examples of this can be found in the <b>JavaTextHover</b>
 implemented with the JDT editor.</p>
 <h3>Ruler hover</h3>
 <p>Hover on the vertical ruler is useful for showing show line-oriented information.&nbsp;
 The hover class is configured as described above.&nbsp; <b><a href="../reference/api/org/eclipse/jface/text/source/IAnnotationHover.html">IAnnotationHover</a></b>
 is the interface for ruler hover objects.&nbsp; 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.&nbsp; 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.&nbsp;&nbsp;&nbsp;</p>
 <p>The Java example editor's <b>JavaAnnotationHover</b>  implements hover for
 all lines.&nbsp; It uses the line number to
 obtain all of the text on the hover line and returning it as the info string.</p>

 <pre>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;
 }</pre>
 <p><img src="images/javarulerhover.png" alt="Hover information on ruler" border="0"></p>
 <p>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.&nbsp; 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.&nbsp; The <b>JavaAnnotationHover</b>
 provided by the JDT editor provides this capability.
 </p>


 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
	<HEAD>

	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
	<TITLE>
	Text and ruler hover
	</TITLE>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<H2>Text and ruler hover</H2>
	<p>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.</p>
	<p>Hover support is optional.  By default, <b><a href="../reference/api/org/eclipse/jface/text/source/SourceViewerConfiguration.html">SourceViewerConfiguration</a>
	</b>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 <a href="editors_sourceviewers.htm">configured</a>
	to define a pluggable hover object.</p>
	<p>Let's look again at <b>JavaSourceViewerConfiguration</b>
	to see which methods define the hover behavior:</p>

	<pre>public ITextHover getTextHover(ISourceViewer sourceViewer, String contentType) {
	return new JavaTextHover();
	}
	public IAnnotationHover getAnnotationHover(ISourceViewer sourceViewer) {
	return new JavaAnnotationHover();
	}
	</pre>
	<p>Hover helper classes can also be installed dynamically using <b><a href="../reference/api/org/eclipse/jface/text/source/SourceViewer.html">SourceViewer</a></b>
	protocol (<b>setTextHover</b> and <b>setAnnotationHover</b>).  There is no
	particular runtime benefit to doing it either way, but putting all of the
	pluggable behavior overrides in a subclass of <b><a href="../reference/api/org/eclipse/jface/text/source/SourceViewerConfiguration.html">SourceViewerConfiguration</a>
	</b>provides the advantage of consolidating all of the definitions in one place.</p>
	<p>Let's look at the specifics of providing both kinds of hover.</p>
	<h3>Text hover</h3>
	<p>Text hover allows you to provide informational text about text shown in the
	editor.  This is done using the <b><a href="../reference/api/org/eclipse/jface/text/ITextHover.html">ITextHover</a></b>
	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.  <b>JavaTextHover</b> 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. </p>

	<pre>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);
	}
	}</pre>
	<p>Given its own computed hover region, it obtains the selected text from its
	document and returns that as the hover info.</p>

	<pre>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");
	}
	...
	}</pre>
	<p>Sure enough, we can see that if we hover over a selection in the editor, the
	hover text shows the selection.</p>
	<p><img src="images/javatexthover.png" alt="Hover information on selected region" border="0"></p>
	<p>More complicated contextual information can be used to compute useful hover
	information.  Examples of this can be found in the <b>JavaTextHover</b>
	implemented with the JDT editor.</p>
	<h3>Ruler hover</h3>
	<p>Hover on the vertical ruler is useful for showing show line-oriented information.
	The hover class is configured as described above.  <b><a href="../reference/api/org/eclipse/jface/text/source/IAnnotationHover.html">IAnnotationHover</a></b>
	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.   </p>
	<p>The Java example editor's <b>JavaAnnotationHover</b> 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.</p>

	<pre>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;
	}</pre>
	<p><img src="images/javarulerhover.png" alt="Hover information on ruler" border="0"></p>
	<p>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 <b>JavaAnnotationHover</b>
	provided by the JDT editor provides this capability.
	</p>


	</BODY>
	</HTML>