com.googlecode.gchart.client
Interface HoverParameterInterpreter

public interface HoverParameterInterpreter

Translates parameter names into plain text or HTML snippets that represent that parameter's value at a given, "hovered over", point.

By passing an instance of a HoverParameterInterpreter to GChart's setHoverParameterInterpreter method, you can teach GChart how to expand custom parameters embedded in hovertext templates (c.f. setHovertextTemplate) in a manner analogous to how it expands the built-in parameters ${x}, $(y), and ${pieSliceSize}.

Note: You can also use a hover parameter interpreter to override the built-in parameters, giving them a different meaning, numeric format, etc., if you like.

The Chart Gallery chart below uses a custom hover parameter interpreter that allows hover text to include the number (positional index) of the curve that contains the hovered over point:

package com.googlecode.gchart.gcharttestapp.client;
import com.googlecode.gchart.client.GChart;
import com.googlecode.gchart.client.HoverParameterInterpreter;
/**
 * Illustrates how to use a <tt>HoverParameterInterpreter</tt> to define
 * your own custom parameter names that GChart will then expand when
 * included in a hover text template via <tt>setHovertextTemplate</tt>.
 * <p>
 *
 * This example adds a custom parameter called <tt>curveNumber</tt> that
 * expands into the index of the curve containing the hovered over
 * point.
 *
 * 
 */
public class GChartExample17 extends GChart {

 class CurveNumberHoverParameterInterpreter
       implements HoverParameterInterpreter {
 
   public String getHoverParameter(String paramName,
                            GChart.Curve.Point hoveredOver) {
                            
  // Returning null tells GChart "I don't know how to expand that
  // parameter name". The built-in parameters (${x}, ${y}, etc.) won't
  // be processed correctly unless you return null for this "no
  // matching parameter" case.
      String result = null; 
      if ("curveNumber".equals(paramName)) {
       // The parent of a point is the curve containing it, and the
       // parent of that curve is the GChart itself. So, from the
       // single hovered over point ref., we can get at any info
       // within the GChart we may need to generate our snippets.
           result = "" +
             hoveredOver.getParent().getParent().getCurveIndex(
               hoveredOver.getParent());
      }
      // add "else if" branches to support more parameter names

      return result;
    }

  }

  GChartExample17() {
     setChartSize(200, 200);
     setBorderWidth("0px");
     setHoverParameterInterpreter(
        new CurveNumberHoverParameterInterpreter());
     String template = GChart.formatAsHovertext(
                         "Curve #${curveNumber}:<br>x=${x}, y=${y}");
     for (int iCurve = 0; iCurve < 3; iCurve++) {
       addCurve();
       getCurve().getSymbol().setHovertextTemplate(template);
       for (int iPoint = 0; iPoint < 10; iPoint++) 
          getCurve().addPoint(iPoint, (iCurve+1)*iPoint);
     }
  }
}

Now, whenever the user hovers over a point on any curve, the curve index, along with x,y coordinates, appears in the hover text. Here's what the chart looks like when the user hovers over the last point of the first curve:

Note how, once defined, ${curveNumber} can be used in a manner very similar to how the built-in parameters work. Some applications may even allow end-users to edit/generate hover template HTML that displays just the information they are interested in.

If you're looking for something that provides a more convincing case for using a HoverParameterInterpreter, see this more realistically complex example.

Tip: An easy way to format numeric custom parameters is via the formatAsTickLabel method, since tick label formats are often appropriate for numeric hovertext values, too. Note that the built-in hover parameters (${x}, ${y}, etc.) use this approach.

Tip: If you need more control over the hover feedback than can be provided by expanding parameter names embedded in an HTML template string, consider using a HoverUpdateable widget. You can also use both techniques together by invoking hoveredOverPoint.getHovertext from within your hover widget's hoverUpdate method.

See Also:

setHovertextTemplate, getHovertext, formatAsTickLabel, HoverUpdateable, setHoverParameterInterpreter, setBrushHeight

Method Summary

java.lang.String

getHoverParameter(java.lang.String paramName, GChart.Curve.Point hoveredOver) Returns the value of the named parameter evaluated at the given "hovered over" point.

Method Detail

getHoverParameter

java.lang.String getHoverParameter(java.lang.String paramName,
                                   GChart.Curve.Point hoveredOver)

Returns the value of the named parameter evaluated at the given "hovered over" point. The string should be a plain text or HTML snippet that will be substituted for any ${...} bracketed occurrences of the parameter in any hovertext template string on any chart that uses this hover parameter interpreter.

Parameters:

paramName - the name of the custom parameter. The name must begin with a letter (a,b,...z or A,B,...Z), and be followed by a sequences of letters, digits (0,1,..,9) or underscores (_).

hoveredOver - a reference to the point that the mouse centered brush is currently touching (hovering over). GChart will never invoke this method with a null Point reference.

Returns:

a plain text or HTML snippet representing the value of the named parameter at the hovered-over point, or null if this parameter interpreter does not recognize the given parameter name.

See Also:

HoverParameterInterpreter