com.googlecode.gchart.client
Class GChart.Symbol

java.lang.Object
  com.googlecode.gchart.client.GChart.Symbol

Enclosing class:

GChart

public class GChart.Symbol
extends java.lang.Object

Defines a chart curve symbol. Each point on a curve is represented on the chart by an appropriate rendering of the curve's symbol.

See Also:

Curve.getSymbol, SymbolType

Method Summary

java.lang.String	getBackgroundColor() Returns the CSS background color of all the rectangular elements used in rendering the symbol.
double	getBaseline() Returns the baseline value for this symbol, previously specified via setBaseline
java.lang.String	getBorderColor() Returns the CSS border color of all the rectangular elements used in rendering the symbol.
java.lang.String	getBorderStyle() Returns the border style of all of the rectangular elements from which this symbol is built.
int	getBorderWidth() Returns the width of the border around each rectangular element used to render this symbol, in pixels.
boolean	getFillHasHovertext() Returns a value indicating if interpolated and filled-in elements associated with non-rectangular aspects of a symbol get the same kind of hovertext as non-filled elements do.
double	getFillSpacing() Returns the spacing between successive rectangular elements used to emulate any required non-rectangular features of the symbol.
int	getFillThickness() Returns the "thickness" of rectangular elements used to emulate any required non-rectangular features of the symbol.
int	getHeight() Returns this symbol's height, as previously set by setHeight.
java.lang.String	getHovertextTemplate() Returns the hovertextTemplate of this symbol.
java.lang.String	getImageURL()
double	getModelHeight() Returns this symbol's height as previously set by setModelHeight.
double	getModelWidth() Returns this symbol's width as previously set by setModelWidth.
GChart.Curve	getParent() Returns the Curve that contains this Symbol.
double	getPieSliceOrientation() Returns the value, previously specified via setPieSliceOrientation, that defines the angular orientation of any pie slices associated with this symbol.
double	getPieSliceSize() Returns the value, previously specified via setPieSliceSize, that defines the size of the angle subtended by any pie slice associated with this symbol.
GChart.SymbolType	getSymbolType() Returns this symbol's type.
int	getWidth() Returns this symbol's width as previously set by setWidth.
void	setBackgroundColor(java.lang.String backgroundColor) Specifies theCSS background color of all the rectangular elements used in rendering this symbol.
void	setBaseline(double baseline) Specifies the baseline value for this symbol.
void	setBorderColor(java.lang.String borderColor) Specifies the CSS border color of all the rectangular elements used in rendering this symbol.
void	setBorderStyle(java.lang.String borderStyle) Sets the border style of the rectangular elements used to render this symbol.
void	setBorderWidth(int borderWidth) Sets the width of the border around each rectangular element used to render this symbol's border, in pixels.
void	setFillHasHovertext(boolean fillHasHovertext) Specifies if interpolated and filled-in rectangular elements, generated to render any required non-rectangular aspects of symbol, have hovertext added to them as defined by the symbol's hovertextTemplate.
void	setFillSpacing(double fillSpacing) Specifies the spacing between successive rectangular elements used to render any required non-rectangular features of the symbol.
void	setFillThickness(int fillThickness) Sets the "thickness" of the rectangular elements used to render any required non-rectangular features of this symbol.
void	setHeight(int height) Sets the height of this symbol (including any specified border) in pixels.
void	setHovertextTemplate(java.lang.String hovertextTemplate) Defines the "hover-text" that appears whenever the user points their mouse at a point on the curve.
void	setImageURL(java.lang.String imageURL) Specifies the URL that will define the image used to represent the points on this curve.
void	setModelHeight(double modelHeight) Sets the height of this symbol (including any specified border) in model units (arbitrary, user-defined, units).
void	setModelWidth(double modelWidth) Sets the width of this symbol (including any specified border) in model units.
void	setPieSliceOrientation(double pieSliceOrientation) Specifies a value that defines the angular orientation of the first edge of the pie slice associated with this symbol.
void	setPieSliceSize(double pieSliceSize) Specifies a value that defines the angular size of any pie slice associated with this symbol.
void	setSymbolType(GChart.SymbolType symbolType) Sets the type of this symbol.
void	setWidth(int width) Sets the width of this symbol (including any specified border) in pixels.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getImageURL

public java.lang.String getImageURL()

setImageURL

public void setImageURL(java.lang.String imageURL)

Specifies the URL that will define the image used to represent the points on this curve.

Specify null to use the URL returned by getBlankImageURL (this is the default, and gives you a blank 1x1 pixel GIF).

Most applications will do just fine with the default. However, this method lets you replace the default, rectangular, chart symbols with custom images (e.g. a five pointed star) or even a Google Chart API url to use tiny 3-D pie charts for each point symbol (it looks a bit strange, and your chart will no longer be strictly client-side any more, but it does work).

Note that if the symbol's width and height are bigger or smaller than the specified image, the image will be stretched to fit the symbol's size. Except for single pixel images and such, this does not usually look that great, so exactly matching up the symbol and image size is often best.

Be aware that GChart was originally designed with only blank image URL's in mind, so it may take some effort to adjust other settings (such as symbol type, width, height, background color, border color, various legend related settings, and curve order) so that the overall chart looks right with your custom images for the curve symbols. In particular, the legend icons are just scaled-down versions of the image, which often doesn't look that great.

A alternative that gives you more control (but is less efficient) is to use SymbolType.NONE with setAnnotationWidget (or setAnnotationText) and setAnnotationLocation(AnnotationLocation.CENTER) to use separate, centered, widget-based (or HTML based) annotations in lieu of each point's image-based symbol.

Parameters:

imageURL - the url that defines the image within all the rectangular elements used to draw this symbol on the chart, or null to revert to GChart's default (a 1x1 transparent blank GIF).

See Also:

setImageURL, setBlankImageURL, setPlotAreaImageURL, setAnnotationWidget, setAnnotationText, setAnnotationLocation, setSymbolType, SymbolType.NONE

getBackgroundColor

public java.lang.String getBackgroundColor()

Returns the CSS background color of all the rectangular elements used in rendering the symbol.

Returns:

the CSS background color used to fill in the central (non-border) part of each rectangular element used to render a curve's symbol.

See Also:

setBackgroundColor

getBaseline

public double getBaseline()

Returns the baseline value for this symbol, previously specified via setBaseline

Returns:

the previously specified baseline value for this symbol.

See Also:

setBaseline

getBorderColor

public java.lang.String getBorderColor()

Returns the CSS border color of all the rectangular elements used in rendering the symbol.

Returns:

the color of the border of the rectangular elements used to render the symbol, in standard CSS format

See Also:

setBorderColor

getBorderStyle

public java.lang.String getBorderStyle()

Returns the border style of all of the rectangular elements from which this symbol is built.

Returns:

the CSS borderStyle of this symbol's elements (dotted, dashed, solid, etc. )

See Also:

setBorderStyle

getBorderWidth

public int getBorderWidth()

Returns the width of the border around each rectangular element used to render this symbol, in pixels.

Returns:

the previously set border width (in pixels).

See Also:

setBorderWidth

getFillHasHovertext

public boolean getFillHasHovertext()

Returns a value indicating if interpolated and filled-in elements associated with non-rectangular aspects of a symbol get the same kind of hovertext as non-filled elements do.

Returns:

true if hovertext is added to filled-in elements false if it is not.

See Also:

setFillHasHovertext

getFillSpacing

public double getFillSpacing()

Returns the spacing between successive rectangular elements used to emulate any required non-rectangular features of the symbol.

Returns:

the previously set (or the default, if the fillSpacing has been set to Double.NaN) fill spacing (in pixels).

See Also:

setFillSpacing, setFillThickness

getFillThickness

public int getFillThickness()

Returns the "thickness" of rectangular elements used to emulate any required non-rectangular features of the symbol.

Returns:

the previously set (or the default, if the fillThickness has been set to GChart.NAI) fill thickness (in pixels).

See Also:

setFillThickness, setFillSpacing

getHovertextTemplate

public java.lang.String getHovertextTemplate()

Returns the hovertextTemplate of this symbol.

Returns:

hovertextTemplate of the symbol

See Also:

setHovertextTemplate

getParent

public GChart.Curve getParent()

Returns the Curve that contains this Symbol.

Returns:

a reference to the Curve that contains this Symbol (its "parent")

getPieSliceOrientation

public double getPieSliceOrientation()

Returns the value, previously specified via setPieSliceOrientation, that defines the angular orientation of any pie slices associated with this symbol.

Returns:

the value, either Double.NaN or a value between 0 and 1 previously set via setPieSliceOrientation, that determines the angular orientation of any pie slice associated with this symbol.

See Also:

setPieSliceOrientation, setPieSliceSize

getPieSliceSize

public double getPieSliceSize()

Returns the value, previously specified via setPieSliceSize, that defines the size of the angle subtended by any pie slice associated with this symbol.

Returns:

the value, between 0 and 1 and previously set via setPieSliceSize, that defines the size of the "wedge of pie" as a fraction of the total pie, for any pie slice associated with this symbol.

See Also:

setPieSliceOrientation, setPieSliceSize

getHeight

public int getHeight()

Returns this symbol's height, as previously set by setHeight.

Returns:

the previously set symbol height, in pixels.

See Also:

setHeight

getModelHeight

public double getModelHeight()

Returns this symbol's height as previously set by setModelHeight.

Returns:

the previously set symbol height, in model units

See Also:

setModelHeight, setWidth, setHeight, setWidth

getModelWidth

public double getModelWidth()

Returns this symbol's width as previously set by setModelWidth.

Returns:

the previously set symbol width, in model units.

See Also:

setModelWidth, setModelHeight, setWidth, setHeight

getSymbolType

public GChart.SymbolType getSymbolType()

Returns this symbol's type.

Returns:

the type of this symbol.

See Also:

setSymbolType

getWidth

public int getWidth()

Returns this symbol's width as previously set by setWidth.

Returns:

the previously set symbol width, in pixels

See Also:

setWidth

setBackgroundColor

public void setBackgroundColor(java.lang.String backgroundColor)

Specifies theCSS background color of all the rectangular elements used in rendering this symbol. For example, this would define the color of the non-border part of bars in a bar-chart, the color of the non-border part of each shading bar in a pie slice, etc.

You can use one of the 16 standard HTML/CSS color literals, illustrated below, to quickly specify common colors:

For more variety, use a standard CSS RGB (red, green, and blue) color format such as "#FF0000" (same as "red"), "#00FF00" (same as "green"), "#0000FF" (same as "blue"), "#FFFFFF" (same as "white") or "#000000" (same as "black").

The default symbol background color is DEFAULT_SYMBOL_BACKGROUND_COLOR

Parameters:

backgroundColor - standard CSS color-defining string

See Also:

getBackgroundColor, setBorderColor, DEFAULT_SYMBOL_BACKGROUND_COLOR

setBaseline

public void setBaseline(double baseline)

Specifies the baseline value for this symbol. Use a baseline value when you need to create bar charts whose bars extend up/down to a specified y baseline value (for vertical bar charts) or left/right to a specified x baseline value (for horizontal bar charts).

In greater detail:

• For curves that employ symbol types with names of the form VBAR_BASELINE_*, a vertical bar is drawn that connects the x,y position of each data point to the horizontal line defined by the equation y=baseline. For the default baseline setting of Double.NaN, the defining equation is y=(yMin+yMax)/2 (i.e., a midpoint baseline).

• For curves that employ symbol types with names of the form HBAR_BASELINE_*, a horizontal bar is drawn from the x,y position associated with each data point to the vertical line defined by the equation x=baseline. For the default baseline setting of Double.NaN, the defining equation is x=(xMin+xMax)/2.

Parameters:

baseline - the y (or x) that defines the horizontal (or vertical) line to which any baseline-based vertical (or horizontal) bars are extended.

See Also:

getBaseline, HBAR_BASELINE_CENTER, HBAR_BASELINE_SOUTH, HBAR_BASELINE_NORTH, VBAR_BASELINE_CENTER, VBAR_BASELINE_EAST, VBAR_BASELINE_WEST

setBorderColor

public void setBorderColor(java.lang.String borderColor)

Specifies the CSS border color of all the rectangular elements used in rendering this symbol.

For example, for a square symbol, this would set the color of the line that indicates the outter perimeter of that square. However, for a pie slice, this would set the color of the outter perimeter of every shading bar used to fill in the pie slice.

Tip: Although you can use the special CSS keyword "transparent", different GWT-supported browsers have different rules for deciding what color is "behind" an element's border, and thus they can sometimes render "transparent" differently. The easiest way to assure consistent border colors across all GWT-supported browsers is to use explicit colors, rather than "transparent", for borders whenever you can. For example, if you know that the plot area's background is gray, set the border to "gray" to obtain approximately the same result as if the border were "transparent".

Parameters:

borderColor - the color of the border around each rectangular element used to render the symbol, in the standard CSS color format. For more information on standard CSS color specifications see setBackgroundColor.

See Also:

getBorderColor

setBorderStyle

public void setBorderStyle(java.lang.String borderStyle)

Sets the border style of the rectangular elements used to render this symbol.

Parameters:

borderStyle - a CSS border style such as "solid", "dotted", "dashed", etc.

See Also:

getBorderStyle, setBackgroundColor, setBorderColor

setBorderWidth

public void setBorderWidth(int borderWidth)

Sets the width of the border around each rectangular element used to render this symbol's border, in pixels.

If the symbol's width or height ever become less than twice the specified border width, the border will be shrunk down until it just fills up the entire rectangular area of the symbol.

Parameters:

borderWidth - the width of the symbol's border, in pixels

See Also:

getBorderWidth

setFillHasHovertext

public void setFillHasHovertext(boolean fillHasHovertext)

Specifies if interpolated and filled-in rectangular elements, generated to render any required non-rectangular aspects of symbol, have hovertext added to them as defined by the symbol's hovertextTemplate.

For example, in a line chart, the symbol has two aspects: a symbol representing the data point itself, and a series of "dots" that connect that point to any subsequent point. If this property is true, both the rectangular element representing the data point itself, as well as any interpolated "dots" have, say, a hovertext that indicates their x,y coordinates. If false, the elements representing the data points, but not the interpolated elements, get such hovertext.

Note: In earlier versions, turning off fill hovertext made GChart updates faster. Because (as of GChart 2.1) hovertext generation is now deferred until mouse-overs, there's usually no longer a speed advantage to turning off hovertext, unless you have so many elements that hovering itself becomes a performance bottleneck. However, it may still save significant amounts of memory to turn off fill hovertext. In general, unless you want people to be able to hover over the filled-in points and see their values, it's best to disable fill hovertext.

Parameters:

fillHasHovertext - true (the default) if you want interpolated/filled-in elements to have hovertext, false if you don't want such hovertext.

See Also:

getFillHasHovertext, setHovertextTemplate

setFillSpacing

public void setFillSpacing(double fillSpacing)

Specifies the spacing between successive rectangular elements used to render any required non-rectangular features of the symbol.

The exact meaning of this spacing setting depends on the symbol type:

SymbolType	How spacing is interpreted	Default value
BOX_*	The distance between the centers of the "dots" used to draw the dotted connecting lines between successive x,y data points on a curve.	4
PIE_SLICE_*	The vertical or horizontal distance between corresponding edges of the vertical, and/or horizontal, shading bars used to fill in the pie slice	4
VBAR_*	The horizontal distance between corresponding edges of the vertical bars used to fill in the trapezoidal areas linearly interpolated between successive vertical bars on a curve.	4
HBAR_*	The vertical distance between corresponding edges of the horizontal bars used to fill in the trapezoidal areas linearly interpolated between successive horizontal bars on a curve.	4

Although by using a spacing and thickness setting of 1 px you can produce continous lines, solid fill pie slices, etc. since the number of elements required is inversely proportional to fill spacing, using such a small fill spacing could degrade performance unacceptably, especially for very large charts. On the other hand, too large a fill spacing/thickness can degrade graphical quality unacceptably (e.g. due to too few "dots" on dotted connecting lines, "grainy filled" pie slices, etc.). Experience suggests that many applications will be able to find intermediate spacing/thickness settings that provide an acceptable level of both graphical quality and performance--particularly if your charting needs are more utilitarian than aesthetic.

Though GChart's "just say it with rectangles" approach greatly simplifies its implementation and consequently delivers many practical benefits, it limits the visual quality of the charts. If the aesthetics of your site require more (sometimes only a 3-D pie chart with drop-shadows and all the trimmings will do) you may have to use one of the many GWT-accessible, vector-graphics-based, charting packages such as jFreeChart, Google Chart API, Dojo Charting, PlotKit, timepedia's Chronoscope, YUI Charts, etc. Or consider a hybrid approach in which GChart annotations (via setAnnotationWidget) or image urls (via setImageURL) are used to precisely place, say, server-generated images onto an otherwise client-based GChart.

Parameters:

fillSpacing - spacing between successive rectangular elements used to fill in non-rectangular symbols, in pixels.

See Also:

getFillSpacing, setFillThickness

setFillThickness

public void setFillThickness(int fillThickness)

Sets the "thickness" of the rectangular elements used to render any required non-rectangular features of this symbol.

The exact meaning of this thickness setting, as well as the default used whenever the thickness is set to the special undefined integer value recognized by GChart (GChart.NAI), depends on the symbol type:

SymbolType	How thickness is interpreted	Default value
BOX_*	The height and width of rectangular "dots" used to draw the dotted connecting lines between successive x,y data points on a curve.	0 (implies no interpolated dots)
PIE_SLICE_*	The width of vertical, and/or the height of horizontal, shading bars used to fill in the pie slice	2
VBAR_*	The width of vertical bars used to fill in the trapezoidal areas linearly interpolated between successive vertical bars on a curve.	0 (implies no "area filling" between bars)
HBAR_*	The height of horizontal bars used to fill in the trapezoidal areas linearly interpolated between successive horizontal bars on a curve.	0 (implies no "area filling" between bars)

This fill thickness setting and the associated fill spacing setting (c.f. setFillSpacing) work together to define the look and efficiency of pie slice shading, connecting lines, etc.

Parameters:

fillThickness - the fill thickness, in pixels

See Also:

getFillThickness, setFillSpacing

setHovertextTemplate

public void setHovertextTemplate(java.lang.String hovertextTemplate)

Defines the "hover-text" that appears whenever the user points their mouse at a point on the curve.

Three special keywords, ${x}, ${y}, and ${pieSliceSize} are supported within the hover-text String. Any occurrences of ${x} in the string will be replaced with the x-coordinate of the point, formatted as per the specified tick label format of the x-axis. Any occurrences of ${y} within the string will be replaced with the y-coordinate of the point, formatted either using the y-axis or y2-axis tick label format, depending on the axis on which the curve is displayed. Any occurances of ${pieSliceSize} within the string will be replaced with 100 times the specified pieSliceSize of the point, formatted the same way as ${y}, except that a "%" is tacked onto the end.

Tip: If the ${ is not followed by a recognized keyword and then by }, the "invalid keyword" passes through literally into the final hovertext (no exception is thrown). So, if you see keywords in your hovertext, it probably means you misspelled a keyword (e.g. you entered ${piesliceSize} instead of ${pieSliceSize}).

The default hovertext template, used automatically if hovertext template is null, is DEFAULT_PIE_SLICE_HOVERTEXT_TEMPLATE for pie slice type symbols and DEFAULT_HOVERTEXT_TEMPLATE for all other symbol types.

HTML is not supported within hover-text.

The original keywords XXX and YYY of version 1.1, which were deprecated in version 2.0, have been dropped as of version 2.1. If you used these keywords, simply replace each XXX in your template text with ${x} and each YYY with ${y}. Support was dropped to simplify/speedup the code performing hovertext template parameter substitutions.

Parameters:

hovertextTemplate - defines the hoverText to display when the mouse moves over a point on this curve, with ${x}, ${y} and ${pieSliceSize} keywords replaced as described above.

See Also:

getHovertextTemplate, setFillHasHovertext, DEFAULT_HOVERTEXT_TEMPLATE, DEFAULT_PIE_SLICE_HOVERTEXT_TEMPLATE

setHeight

public void setHeight(int height)

Sets the height of this symbol (including any specified border) in pixels.

Symbols for drawing vertical bars and symbols defining vertical lines between points or across the entire chart, compute their heights automatically based on curve data, axes limits, specified baselines, etc. These symbols, namely XGRIDLINE and all those whose names begin with VBAR_ will ignore this height setting.

Parameters:

height - height of this symbol, in pixels.

See Also:

getHeight

setModelHeight

public void setModelHeight(double modelHeight)

Sets the height of this symbol (including any specified border) in model units (arbitrary, user-defined, units). Model units are the same units in which the points on the chart are specified and charted.

Specification of the modelHeight undefines (that is, sets to GChart.NAI) any previous pixel-based specification made via setHeight.

Symbols for drawing vertical bars and symbols defining vertical lines between points or across the entire chart, compute their heights automatically based on curve data, axes limits, specified baselines, etc. These symbols, namely XGRIDLINE and all those whose names begin with VBAR_ will ignore this height setting.

Parameters:

modelHeight - height of this symbol, in model units

See Also:

getModelHeight, setHeight, setModelWidth, setWidth

setModelWidth

public void setModelWidth(double modelWidth)

Sets the width of this symbol (including any specified border) in model units. Model units are an arbitrary, user-defined units system associated with the x,y coordinates of points displayed on the chart.

Specification of a symbol's model width undefines (that is, sets to GChart.NAI) any previous, pixel-based, width specification made via setWidth.

Symbols for drawing horizontal bars, and symbols defining horizontal lines between points or across the entire chart, compute their widths automatically based on curve data, axes limits, specified baseline, etc. These symbols, namely YGRIDLINE and all those whose names begin with HBAR_ will ignore this width setting.

Parameters:

modelWidth - width of this symbol, in model units.

See Also:

setModelHeight, setWidth, setHeight

setPieSliceOrientation

public void setPieSliceOrientation(double pieSliceOrientation)

Specifies a value that defines the angular orientation of the first edge of the pie slice associated with this symbol. (An additional clockwise rotation as defined by setPieSliceSize defines the angular orientation of the second edge of the pie slice).

When specified explicitly, the value must be a fraction >= 0 and < 1, with 0 representing due south, 0.25 an additional clockwise angular rotation (starting at due south) that is 25% of the full, 360 degree rotation (and thus, if you can follow these gyrations, is due west), 0.5 representing a 50% clockwise angular rotation from due south (thus, due north), .75 a 75% clockwise rotation (and thus, due east), etc.

If the specially recognized value, Double.NaN, is specified, orientation is chosen so as to make this slice appear adjacent to the previous slice, (assuming it has the same x,y as the previous slice and is thus part of the same pie figure). If this symbol/point represents the very first pie slice, Double.NaN causes the slice to be oriented as specified via the setInitialPieSliceOrientation method (by default, that's due south). Note that though this value can be set regardless of the symbol's SymbolType, it only has an impact on how the symbol is rendered if the symbol has one of the pie slice symbol types (e.g. PIE_SLICE_VERTICAL_SHADING).

Parameters:

pieSliceOrientation - angle at which first edge of pie slice appears, expressed as a fraction of a full 360 degree (2*Pi radians) clockwise rotation from an initial due south position (the 6 o'clock position) required to reach the first edge of the pie slice.

See Also:

getPieSliceOrientation, setPieSliceSize, setInitialPieSliceOrientation

setPieSliceSize

public void setPieSliceSize(double pieSliceSize)

Specifies a value that defines the angular size of any pie slice associated with this symbol.

This must be value between 0 and 1. 0.25 represents a quarter pie slice, 0.5 a half pie, 1 a full pie, etc.

Note that though this value can be set regardless of the symbol's current SymbolType, it only has an impact on how the symbol is rendered if the symbol has one of the pie slice symbol types (e.g. PIE_SLICE_VERTICAL_SHADING).

Parameters:

pieSliceSize - Fraction of a full pie subtended by this particular pie slice. Must be between 0 and 1, inclusive.

See Also:

getPieSliceSize, setPieSliceOrientation

setSymbolType

public void setSymbolType(GChart.SymbolType symbolType)

Sets the type of this symbol.

Parameters:

symbolType - the new symbol type for this symbol.

See Also:

SymbolType

setWidth

public void setWidth(int width)

Sets the width of this symbol (including any specified border) in pixels.

Symbols for drawing horizontal bars, and symbols defining horizontal lines between points or across the entire chart, compute their widths automatically based on curve data, axes limits, specified baseline, etc. These symbols, namely YGRIDLINE and all those whose names begin with HBAR_ will ignore this width setting.

Parameters:

width - width of this symbol, in pixels

See Also:

setHeight