To make things happen when the user clicks on a point, follow these steps:
Read this Chart Gallery code for a very simple example. Or, click on a slice of the live demo's editable pie chart for a more realistic one.
Also, by implementing the new HoverParameterInterpreter interface, and passing an instance of your class to the setHoverParameterInterpreter method, you can define custom parameter names that can be embedded in these templates via the same ant-like syntax as the built-in keywords. GChart will replace these embedded parameters with the HTML snippets returned by your HoverParameterInterpreter.
The sine, cosine, and tangent values displayed when you hover over the sine/cosine chart of the live demo are produced via a trigonometric HoverParameterInterpreter. The Chart Gallery also provides this simple example, that defines a custom parameter for including the number (positional index) of the hovered over curve in the hovertext, and this more advanced example that uses custom parameters to display an auto-scrolling, selected-point-centered, table of x,y data below the mouse cursor.
The full point selection rules, which behave in an appropriately different manner for pie slices, can be found in the setBrushHeight javadocs. For a detailed list of exactly what happens when a point is "touched", see the touch method, which allows you to touch points programatically.
Use the setBrushLocation method to "attach" this brush to the mouse at a position other than its center. Use the setDistanceMetric method to adjust the definition of how far away the brush is from the touched point (if more than one point touches the brush the one whose center is closest to the mouse cursor is selected).
The live demo's oil price simulation uses different "single-sided" brush settings for the two main curves on the chart so that one curve gets selected when the user's mouse is near the top of the plot area, and the other gets selected when it is near the bottom.
Though this auto-selection-on-hover capability is the best new feature of GChart 2.4, ironically, the second best is the ability to turn the darn thing off, by invoking setHoverTouchingEnabled(false). Doing so forces the user to actually click to select (or, more importantly, deselect) a point, which in effect turns the GChart into a kind of giant radio button group, with the click-selectable points playing the role of the radio buttons. For an example that exploits this new "single-selection" capability, see GChartExample21.
The setHoverSelectionBorderColor, setHoverSelectionBorderWidth, and setHoverSelectionBackgroundColor methods allow you to place either internal or external borders around the selected point, or overwrite it's center region (background) with a different color.
Using the setHoverSelectionSymbolType method, you can make GChart generate selection feedback as if the selected point had a different symbol type. This technique is used to substitute a vertical line (by using XGRIDLINE as the hover selection symbol type) for the selection cursor on the sine/cosine chart of the live demo.
You can also control the width and height of the selection cursor via setHoverSelectionWidth and setHoverSelectionHeight. You can even define the selection cursor via an image URL via setHoverSelectionImageURL.
Finally, to turn selection feedback completely off, there's setHoverSelectionEnabled(false).
By default, GChart positions the popup hover annotations relative to the rendering of the hovered over point. Pass the setHoverLocation method one of the various AnnotationLocation choices for basic compass-point positioning relative to the hovered-over point and then fine-tune those initial positions via setHoverXShift and setHoverYShift. Rules and conventions are exactly the same as for ordinary annotation positioning via the analogous setAnnotationLocation, setAnnotationXShift, and setAnnotationYShift methods.
But there are other options. Pass one of the new ANCHOR_MOUSE* family of symbol types to the setHoverAnnotationSymbolType method to position hover feedback relative to the location of the mouse (similarly to how conventional, setTitle-based hovertext works). Or, pass in one of the existing 9 compass-point anchoring symbol types (ANCHOR_NORTH, etc.) to make the hover annotation pop up at a fixed location on the chart.
Use setHoverAnnotationEnabled(false) to turn pop-up hover annotations completely off for a curve.
On the live demo, the oil simulation chart places its hover feedback at two different fixed locations on the chart (depending on which curve is selected). The quarterly revenue chart places its hover annotation relative to the mouse cursor. The sine/cosine example horizontally centers it's hover message at the x position of the currently selected point, just above the chart's plot area, via the pairing of setHoverAnnotationSymbolType(SymbolType.XGRIDLINE) with setHoverLocation(AnnotationLocation.NORTH).
That interface has two methods: hoverUpdate(Point hoveredOver), that GChart calls whenever the user moves the mouse over a new point, and hoverCleanup(Point hoveredAwayFrom), that GChart calls whenever a point is deleted, or the user moves away from it.
So, if you need to go a step beyond parameterized HTML templates, you can use an arbitrary GWT Widget to define a hover annotation. You can even arrange things so that the user can interact with the hover widget, which can contain buttons, checkboxes, etc. This provides an interesting alternative to adding a ClickListener to the chart.
All of the positioning and selection features mentioned above for HTML-based hover annotations work exactly the same way for hover widgets, which are just a more elaborate kind of hover annotation.
The live demo uses a secondary, detailed, GChart as this hover widget (GCharts are Widgets, and hence can also be "hover widgets") to define a "detail pie" that changes as you hover over different bars on the quarterly revenue chart. The Chart Gallery also contains this simple hover widget example, as well as this more complicated one.
If you'd like to produce something close to what you had before, the simple (but imperfect) workaround is to just wrap a call to the new GChart.formatAsHovertext method around your old hovertext template strings.
If you want to go further than that, you can emulate an "at the mouse" positioning of popup hover annotations via code such as setHoverAnnotationSymbolType(ANCHOR_MOUSE).
This is described in more detail in the formatAsHovertext and setHoverAnnotationSymbolType javadocs.
One feature of the old hovertext you won't be able to recreate easily is the "timeout" on the display of hovertext. With the new system, the hover annotation remains as long as the mouse is "touching" the point. I expect most applications will consider this an improvement, though.
Finally, if you just really prefer the old, setTitle-based behaviours, I see no reason why you should not be able to reproduce them exactly (have not actually tried this particular combination, though) by using a transparent hover widget (via setHoverWidget), positioned (via setHoverLocation) and sized appropriately so that it covers the rendered points exactly, and then just using that hover widget's setTitle method. You might have to choose a large enough brush size to assure that the transparent hover widget pops up before your mouse is actually on top of the hover widget.
The getCurveIndex method now returns GChart.NAI ("Not An Integer") instead of -1, as its "point not found" indicator.
This change was made to facilitate the (internal) use of negative curve indexes to reference GChart's system curves, and also so that GChart.NAI is consistently used to represent undefined integers throughout GChart.
Workaround: search your code for any getCurveIndex usage that check for a -1 return value, and change these tests to check for GChart.NAI instead. Applications with such code are expected to be rare.
Previously, GChart allowed you to copy its setTitle-based hover text strings into elements used to draw continuous or dotted connecting lines between sucessive individual data points.
The new hover feedback does not provide any popup feedback at all on such connecting lines. Reason: it would have complicated hit testing to have to handle continuous lines. Plus, it's of questionable value to have hover feedback on values that are not real data points, but merely interpolated values.
If you really need this feature, you can workaround this change by generating real data points at the interpolated values, and then charting the so-expanded data sequence.
The newer LINE symbol type can do everything these older symbols can do and more. But, these older symbol types were unusual in ways that made them hard to support with the new hit-testing infrastructure. So, they were made synonymous with LINE, and deprecated.
If you used these symbol types, see the VBAR_NEXT javadocs for more information. My expectation is that very few used these symbol types, since LINE has been the preferred approach for some time now.
Most of my example charts used this setting, so I thought is was a better default in that sense.
There are also some known bugs that only appear in the setShowOffChartPoints(false) mode (see below), so I though it was better to use as a default a mode that didn't have those bugs.
To workaround this change, just add the line setShowOffChartPoints(false); at the top of your chart's code.
These methods closely correspond to the existing family of setAnnotationFont* methods, only that they instead control the font properties of the new pop-up hover annotations facility (described above).
I kept typing in the shorter name by mistake, so I figured it was worth removing the useless "number" part (it's already got a double argument). The old name is still there, but deprecated.
This method (similarly to getCurveIndex) returns the integer index of a given point reference.
New convenience methods that remove points or curves from GChart given the Point or Curve references were added. Previous versions required you to have the object's integer index to perform such deletions.
The new values are:
public static final int DEFAULT_WIDGET_WIDTH_UPPERBOUND = 400; public static final int DEFAULT_WIDGET_HEIGHT_UPPERBOUND = 400;Widgets sized greater than the default upper bound will not be properly centered or right justified unless you specify a larger upper bound in the arguments passed into the setAnnotationWidget or setHoverWidget methods.
I increased these defaults so that my example charts could all get away with using them. There is a small performance penalty for using a larger than required default upper bound.
This method adds a black border and a yellow background to a text string passed to it, in order to provide a reasonable approximation of setTitle-like hover text formatting (Sorry, there's no drop shadow. If you've got a neatly formatted self-contained HTML snippet that places a drop shadow around an arbitrarily sized text string, please send it to me and I'll add it to the next release).
This method is provided to simplify the transition from the setTitle based hover text of previous GChart versions. In those versions, only single line plain text hovertext templates were supported.
In the new version, both HTML and plain text (and, via setHoverWidget, GWT Widgets) are allowed. Plain text hovertext template, however, now give you plain black text on a transparent background, which means that, without modification, hover text will look a lot different in the new version.
By simply wrapping a call to this method around your old plain text hovertext template strings (specified via setHovertextTemplate) you will get something a lot closer to what you had in previous versions. Of course, you are now free to use any HTML you like in your hovertext template string, so you are not limited to what you get with this method.
Be sure to prefix your own HTML template strings with <html> (otherwise, GChart treats them as plain text).
For convenience, GChart now interprets negative border widths to mean "add a border of that thickness around the outside of the symbol--increasing the visual size of the symbol". Positive border width continues to imply an internal border that does not change the visual symbol size.
These new negative/external borders do not change the symbol's size from a hit-testing perspective. The size increases are display-only.
An extra, radial, "cut line" could be inappropriately added to full pie slices when non-transparent, differently colored, borders and backgrounds were specified for the slice. Full-pie special case code was added that corrects this problem.
The well known "IE6 makes transparent borders black" problem created an IE6-only bug in my hover selection feedback that lead to my adding this feature to fix it (and help others in the same fix).
If you'd like to use a transparent border on one of your curve's symbols, and don't want it to be black in IE6, or to behave differently in FF2 from how it behaves in IE7 (the IE6 thing isn't the only cross-browser inconsistency with transparent borders) use this keyword instead of the standard CSS "transparent" (which you can of course still use if you like).
For more information, see the TRANSPARENT_BORDER_COLOR javadocs.
Previously, GChart's heuristic for estimating an upper bound on the height associated with an HTML snippet only recognized <br> and <li> as "line delimiters". Now, it also recognizes <tr>. This change allows it to produce reasonable upper bound height estimates for HTML snippets that define tables. Thus, you should not have to override these defaults using the appropriate arguments of the setAnnotationText or setHoverWidget methods as frequently.
The complete set of browsers we test on before each release is:
It's quite likely it works on other browsers, too, but these are the only ones we test on. If you have a different browser, you can visit our live demo and test page to see for yourself.
GChart organizes points into bins/bands at update time so that it can do its hit testing calculations very quickly when the user is mousing over your chart.
Unfortunately, this step, which requires another pass over all the points on the chart, makes updates (very roughly) 15% slower (it also requires 1 to 2 integers worth of extra memory per data point).
You can recoup these update time losses by using setHoverSelectionEnabled(false) and setHoverAnnotationEnabled(false) to turn each curve's hover feedback completely off.
You can often reduce this performance hit to a minimum, without losing your hover feedback, by squeezing all of your chart's hover feedback onto a single curve, and disabling hover feedback on every other curve.
Finally, GChart typically runs several times faster in FF3 and Chrome than in the older browsers. That should help, too.
Some of these bugs are symptoms of the fact that canvas and HTML rendering are different enough that I have not yet come up with a way to make them play together that feels like the right approach for more than a week. If there is another Client-side GChart enthusiast out there with ideas on how to integrate canvas rendering into the product (whose HTML rendering assumptions I'm afraid run rather deep) I'd appreciate hearing from you.