This release provides faster, better looking, alpha-transparent, area, line, and pie charts via a new canvas-powered rendering option.
Compare the new live demo with the old live demo to get a quick feel for the canvas-powered performance and visual quality improvements you can expect with this release.
To access these features, you'll need to plug an external canvas library into GChart (GWTCanvas in the gwt-incubator is reccommended) as described in detail in the setCanvasFactory method.
With the external canvas in place, the next step is to tell GChart you want a curve to be "continuously filled" by invoking setFillSpacing(0).
With each such continuously filled curve, GChart automatically exploits your external canvas library to improved the quality and speed of that curve's rendering. Specifically, banded-filled pie slices become solid filled, dotted connecting lines become continuously connected, and (the biggest stretch) bar charts become area charts. See the setFillSpacing method's javadocs for a detailed description of how each existing symbol type implements this new "continuously-filled", canvas-powered, rendering option.
Note that GChart's previous HTML-only rendering is still available, and is the default rendering mode if you don't bother to plug in an external canvas. Or, to request GChart's standard HTML-only rendering on a single curve, just use a fillSpacing > 0 for that curve.
Though there are exceptions (certain line chart update scenarios can be over three times faster than before, and, on the other hand, simple bar charts will look and perform about the same) most applications can expect to see modest performance gains (say, 25% faster), coupled with greatly improved visual chart quality.
Note on GWT 1.5.3 ==> 1.6 transition
This release has been tested in both GWT 1.5.3 and 1.6. However, 1.6 developers will have to continue to use the (deprecated in 1.6) 1.5.3 event handling idioms for now. A follow up release that migrates GChart to use all the new 1.6 idioms (and that will not be tested in 1.5.3) is planned. I took this approach because I did not want to delay the release (it's been over four months) any further, plus I wanted to have one last, up-to-date, stable, 1.5.3-compatible release for those who may need to stick with 1.5.3 for some reason.Detailed change log:
With this release, setFillSpacing(0) is now legal, and means "continuously fill the curve that uses this symbol".
When an external canvas facility has been interfaced to GChart via setCanvasFactory, and a non-zero fillThickness has been specified, this setting will produce crisply/quickly rendered solid-fill pie, line, and area charts, with alpha-transparency (via the new RGBA color specs described below).
To see these faster, better-looking, pie, line, and area charts visit the now canvas-powered live demo.
Some of the default and fillSpacing values were changed from 1 to 0 in order to assure that the canvas-based rendering kicks in by default whenever possible. If no external canvas has been interfaced to GChart the new 0 setting is treated the same as a 1.
See the setFillSpacing javadoc for full details.
The setBackgroundColor and setBorderColor methods now support RGBA (for example, rgba(255,0,0,0.5) for semi-transparent red) color specifications.
The new alpha-transparency support only works for the canvas-rendered aspects of each curve. For HTML-rendered aspects, GChart quietly collapses the RGBA specs into standard RGB (e.g. rgba(255,0,0,0.5) ==> rgb(255,0,0)).
LINE_CANVAS symbol type is now just another name for LINE, and deprecated.
Basically, GChart now exploits your external canvas library whenever "continuous filling" (via setFillSpacing(0)) has been requested. So the special LINE_CANVAS symbol type of previous versions is no longer needed.
Gridlines, axes, and so forth, now use the border color, rather than the background, which means they render properly in printouts without this browser option tweaking.
More generally, in previous versions, odd-width or height elements always had at least 1 px of background-rendered width or height in the middle of the element, even if the border was large enough to take up the entire element. GChart now uses an asymetrical border to assure that in these cases, the entire symbol is rendered via the border (and thus will print without an "empty line" of background through the middle of the symbol).
Thus, the only thing that won't print are background-specified colors of HTML-rendered chart symbols (bars, rectangular point markers, etc), and the plot area background color. This is sometimes a feature (saves ink) but you can easily work around it. For symbols, you can simply use oversized borders that fill up the entire symbol or, with a little more work to create appropriate images files, define the HTML-rendered symbol's interior via the setImageURL method. Similarly, to make the plot area background printable, use the setPlotAreaImageURL method.
As a result of this change, it's now straightforward to produce charts that print well without special end-user user effort on all browsers.
The new setTickLabelPadding method allows you to control the amount of padding (blank space) between ticks and their labels, and the new getTickSpace returns the amount of space allocated for ticks outside of the plot area (taking into account the location of the ticks).
New methods setClipToPlotArea and setClipToDecoratedChart have been added, and the corresponding older clipping methods setShowOffChartPoints and setShowOffDecoratedChartGlyphs have been re-implemented in terms of the new methods, and deprecated.
Specific point annotations are completely visible if any part of the annotated symbol is visible within the plot area, and completely hidden otherwise.
Hover selection feedback and popup hover annotations are never clipped to the plot area.
This method was never used, but was originally included in the interface for possible future use.
The new canvas rendering approach uses multiple, possibly overlapping, canvas Widgets and thus requires that each have a transparent background. Thus this method is now unlikely ever to be needed, so it has been dropped from the GChartCanvasLite interface.
Though not required, to eliminate clutter, it's best to delete any GChartCanvasLite wrapper code that you may have written to define the dropped setBackgroundColor method.
This is largely an internal change, originally motiviated by the need to integrate canvas rendering while preserving a consistent z-order with a curve's HTML-rendered elements.
But, there is one important performance related improvement as a result of this change: if only one curve has been changed since the last update, the update can be effected without having to re-update any of the other curves. Previously, all curves that came after the modified curve would also have to be re-updated. So, certain specialized update scenarios, such as changes to just the first curve of a multi-curve chart as part of, say, an animation sequence, are now significantly faster.
This is a significant internal implementation change that does not impact the external interface. Previous versions used specialized code to render axis-related elements such as ticks, gridlines, tick-labels, and the axis itself. Now, GChart instead configures special internal system curves that, when rendered as usual, render these chart elements. So, with this release, all GChart chart elements are rendered via curves--either developer defined or internally created by GChart.
This change simplifies the current code and moreover should facilitate the addition of future axis related features such as minor ticks, differently colored or styled gridlines, and a second x axis. The new setTickLocation and setTickLabelPadding methods of this release (described above) are the first installment of these axis-related improvements.
In the new release, the bins only span the plot-area.
Since most applications place all of their points within the plot area, this should provide a very small ("less bins") performance boost for most applications.
However, specialized applications with a very large number of points that are placed outside the plot area could experience a significant hit testing (hover feedback) performance degradation. In the worst case, a linear sequential search over all points would be required during hit testing.
Given that the whole reason for the plot area is to hold the points of the chart, such usage scenarios, though possible, are unlikely.
This change was made to simplify the code changes required to implement the new plot area clipping strategy.
GChart has not been tested in GWT 1.4 for quite some time now, but if you were getting away with it anyway, you will no longer be able to without source code tweaking.
A gap in the selection feedback API was plugged via the addition of the setHoverSelectionFillSpacing and setHoverSelectionFillThickness methods.
It now returns GWT.getModuleBaseURL() + "gchart.gif" by default.
The change was made due to conform better to the new default GWT project folder structure introduced with GWT 1.6; with the new layout, you would get a broken image icon on your charts with the old default.
See setBlankImageURL for more information.
Previous versions used a default annotation location of AnnotationLocation.SOUTH for statically defined point annotations regardless of the symbol type. Whereas dynamic, popup hover-annotations used a symbol-type specific default location.
The current version uses the same, symbol-type-specific defaults for both kinds of annotations. These defaults change in an appropriate manner with symbol type. For example, baseline-based bar charts now, by default, position a point's annotations centered on the edge of the bar farthest from the baseline, which is more likely what you'd want.
To revert to the old convention, simply set the annotation location explicitly via code such as getCurve().getPoint().setAnnotationLocation(AnnotationLocation.SOUTH);
Previously, very small or 0-sized pie slices were often not selectable.
For hit testing purposes only, GChart now widens very small slices so that they have a minimum angle equivalent to +/- 1px along the arc part of the slice. This change makes it easier to select very small slices.
Note that this change does not solve all the problems with small slice selection. For example, in a typical pie chart, if the first slice is very small or 0-sized, it still won't be selectable (you can place the very small slice at the end of the curve list to workaround this problem)
If you need the old behavior of not being able to select very small slices, use a line such as getCurve().getSymbol().setHoverSelectionEnabled(false); to explicitly turn off hover selection on the slice.
GChart now catches any exceptions thrown when making these "is-contained-in" determinations, and then acts as if the element is contained within the opened hoverWidget. This fix can leave hover feedback on the chart when the user mouses away from it at times, but that is something that can happen in a variety of ways already, and so this bug-echo isn't really a serious problem.
Thanks to secnoc for providing the detailed bug report which made it very easy to reproduce and correct this bug.
Previously, setting an annotation on a pie slice without also setting the annotation location raised a null pointer exception when the chart was next updated.
This problem, uncovered inadvertantly during testing of the new clipping strategy (debugging is what happens when you're making other tests) has been corrected.
In some circumstances, horizontal scroll bar ranges could greatly exceed the range needed to display the chart. From a scrolling perspective, it looked like the GChart had added "extra whitespace" to the far right of the page.
This problem was caused by inappropriately large default upper bound width estimates for annotations that used certain kinds of more complex HTML. Though the problem can still occur (these estimates are still not perfect) it is not expected to be as frequent or severe.
Note that you can override these defaults by explicit specification of the widthUpperBound and heightUpperBound parameters of setHoverWidget and similar methods.
This problem was reported as issue 17 by sibiquin.
The new DOM layout described above corrected this problem, as you can see on the sin/cos chart of the live demo.