001 /* Copyright 2007,2008,2009 John C. Gunther
002 *
003 * Licensed under the Apache License, Version 2.0 (the
004 * "License"); you may not use this file except in compliance
005 * with the License. You may obtain a copy of the License at:
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing,
010 * software distributed under the License is distributed on an
011 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
012 * either express or implied. See the License for the specific
013 * language governing permissions and limitations under the
014 * License.
015 */
016
017
018 package com.googlecode.gchart.client;
019
020
021 /**
022 *
023 * Translates parameter names into plain text or HTML snippets that
024 * represent that parameter's value at a given, "hovered over", point.
025 * <p>
026 *
027 * By passing an instance of a <tt>HoverParameterInterpreter</tt> to
028 * GChart's <tt>setHoverParameterInterpreter</tt> method, you can teach
029 * GChart how to expand custom parameters embedded in hovertext
030 * templates (c.f. <tt>setHovertextTemplate</tt>) in a manner analogous
031 * to how it expands the built-in parameters <tt>${x}</tt>,
032 * <tt>$(y)</tt>, and <tt>${pieSliceSize}</tt>. <p>
033 *
034 * <small>
035 * <i>Note:</i> You can also use a hover parameter interpreter to
036 * override the built-in parameters, giving them a different meaning,
037 * numeric format, etc., if you like.
038 * </small>
039 * <p>
040 *
041 * The Chart Gallery chart below uses a custom hover parameter
042 * interpreter that allows hover text to include the number (positional
043 * index) of the curve that contains the hovered over point: <p>
044 *
045 * {@code.sample
046 * ..\..\..\..\..\..\gcharttestapp\src\com\googlecode\gchart\gcharttestapp\client\GChartExample17.java}
047 *
048 * <p>
049 *
050 * Now, whenever the user hovers over a point on any curve, the curve
051 * index, along with x,y coordinates, appears in the hover text. Here's
052 * what the chart looks like when the user hovers over the last point
053 * of the first curve:<p>
054 *
055 * <img
056 * src="{@docRoot}/com/googlecode/gchart/client/doc-files/gchartexample17.png">
057 *
058 * <p>
059 * Note how, once defined, <tt>${curveNumber}</tt> can be used in a
060 * manner very similar to how the built-in parameters work. Some
061 * applications may even allow end-users to edit/generate hover
062 * template HTML that displays just the information they are
063 * interested in.
064 * <p>
065 *
066 * If you're looking for something that provides a more convincing
067 * case for using a <tt>HoverParameterInterpreter</tt>,
068 * see
069 * <a
070 * href="package-summary.html#GChartExample17a">this more realistically
071 * complex example</a>.
072 * <p>
073 *
074 * <i>Tip:</i> An easy way to format numeric custom parameters is via the
075 * <tt>formatAsTickLabel</tt> method, since tick label formats are
076 * often appropriate for numeric hovertext values, too. Note that
077 * the built-in hover parameters (<tt>${x}</tt>, <tt>${y}</tt>, etc.) use this approach.
078 * <p>
079 *
080 * <i>Tip:</i> If you need more control over the hover feedback than can
081 * be provided by expanding parameter names embedded in an HTML template
082 * string, consider using a <tt>HoverUpdateable</tt> widget. You can
083 * also use both techniques together by invoking
084 * <tt>hoveredOverPoint.getHovertext</tt>
085 * from within your hover widget's <tt>hoverUpdate</tt> method.
086 *
087 * @see GChart.Symbol#setHovertextTemplate setHovertextTemplate
088 * @see GChart.Curve.Point#getHovertext getHovertext
089 * @see GChart.Axis#formatAsTickLabel formatAsTickLabel
090 * @see HoverUpdateable HoverUpdateable
091 * @see GChart#setHoverParameterInterpreter setHoverParameterInterpreter
092 * @see GChart.Symbol#setBrushHeight setBrushHeight
093 *
094 */
095 public interface HoverParameterInterpreter {
096
097 /**
098 * Returns the value of the named parameter evaluated at the given
099 * "hovered over" point. The string should be a plain text or HTML
100 * snippet that will be substituted for any <tt>${</tt>...<tt>}</tt>
101 * bracketed occurrences of the parameter in any hovertext template
102 * string on any chart that uses this hover parameter interpreter.
103 * <p>
104 *
105 * @param paramName the name of the custom parameter. The name must
106 * begin with a letter (<tt>a,b,...z</tt> or <tt>A,B,...Z</tt>), and
107 * be followed by a sequences of letters, digits (<tt>0,1,..,9</tt>) or
108 * underscores (<tt>_</tt>).
109 *
110 * @param hoveredOver a reference to the point that the mouse
111 * centered brush is currently touching (hovering over).
112 * GChart will never invoke this method with a <tt>null</tt>
113 * <tt>Point</tt> reference.
114 *
115 * @return a plain text or HTML snippet representing the value of the
116 * named parameter at the hovered-over point, or <tt>null</tt> if
117 * this parameter interpreter does not recognize the given parameter
118 * name.
119 *
120 *
121 * @see HoverParameterInterpreter HoverParameterInterpreter
122 *
123 */
124 public String getHoverParameter(String paramName,
125 GChart.Curve.Point hoveredOver);
126 }