com.googlecode.gchart.client
Class GChart.Curve.Point

java.lang.Object
  com.googlecode.gchart.client.GChart.Curve.Point

Enclosing class:

GChart.Curve

public class GChart.Curve.Point
extends java.lang.Object

Represents a single point on one of the chart's curves. This includes the x, y values of the point in "model coordinates" (arbitrary, application-specific, units), as well as an optional annotation (text label) for the point.

To create points, use a curve's addPoint method.

See Also:

addPoint

Method Summary

java.lang.String	getAnnotationFontColor() Returns the color of the font used to display the point's annotation text.
int	getAnnotationFontSize() Returns the font size of this point's annotation (text label), in pixels.
java.lang.String	getAnnotationFontStyle() Returns the CSS font-style in which the text of this annotation will be rendered.
java.lang.String	getAnnotationFontWeight() Returns true if annotation will be rendered in a bold, or false if in normal, weight font.
GChart.AnnotationLocation	getAnnotationLocation() Returns the previously specified location, relative to the symbol representing the point, of the annotation (text label) associated with this point.
java.lang.String	getAnnotationText() Returns the text of this point's annotation.
boolean	getAnnotationVisible() Returns true is the point's annotation is visible, false otherwise
com.google.gwt.user.client.ui.Widget	getAnnotationWidget() Returns the widget reference that defines this point's annotation as previously specified by setAnnotationWidget.
int	getAnnotationXShift() Returns the distance, in pixels, that this annotation will be shifted along the x-axis from it's default location.
int	getAnnotationYShift() Returns the distance, in pixels, that this annotation will be shifted along the y-axis from it's default location.
GChart.Curve	getParent() Returns the Curve that this point was added to.
double	getX() Returns the x-coordinate of this point in "model units" (arbitrary, application-specific, units).
double	getY() Returns the y-coordinate of this point in "model units" (arbitrary, application-specific, units).
void	setAnnotationFontColor(java.lang.String cssColor) Specifies the color of the annotation's font.
void	setAnnotationFontSize(int fontSize) Specifies the font size of this point's annotation, in pixels.
void	setAnnotationFontStyle(java.lang.String cssStyle) Specifies the CSS font-style used by this point's annotation message.
void	setAnnotationFontWeight(java.lang.String cssWeight) Specifies the weight of the font that will be used to render the text of this point's annotation.
void	setAnnotationLocation(GChart.AnnotationLocation annotationLocation) Specifies the location, relative to this point's symbol, of this point's annotation (text label).
void	setAnnotationText(java.lang.String annotationText) Sets the text of an annotation.
void	setAnnotationText(java.lang.String annotationText, int widthUpperBound, int heightUpperBound) Specifies the text of this point's annotation (label).
void	setAnnotationVisible(boolean isVisible) Specifies if this point's annotation (label) is visible or not.
void	setAnnotationWidget(com.google.gwt.user.client.ui.Widget annotationWidget) Specifies a widget defining this point's annotation.
void	setAnnotationWidget(com.google.gwt.user.client.ui.Widget annotationWidget, int widthUpperBound, int heightUpperBound) Specifies a widget defining this point's annotation
void	setAnnotationXShift(int xShift) Specifies the number of pixels (along the x-axis) to move this point's annotation from its default, AnnotationLocation-defined, position.
void	setAnnotationYShift(int yShift) Specifies the number of pixels (along the y-axis) to move this point's annotation from its default, AnnotationLocation-defined, position.
void	setX(double x) Defines the x-coordinate of this point in "model units" (arbitrary, application-specific, units mapped to the horizontal dimension of the plot area).
void	setY(double y) Defines the y-coordinate of this point in "model units" (arbitrary, application-specific, units mapped to the vertical dimension of the plot area).

Methods inherited from class java.lang.Object

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

Method Detail

getAnnotationFontWeight

public java.lang.String getAnnotationFontWeight()

Returns true if annotation will be rendered in a bold, or false if in normal, weight font.

Returns:

if this annotation is in bold or not.

See Also:

setAnnotationFontWeight

getAnnotationFontColor

public java.lang.String getAnnotationFontColor()

Returns the color of the font used to display the point's annotation text.

Returns:

CSS color string defining the annotation's color

See Also:

setAnnotationFontColor

getAnnotationFontStyle

public java.lang.String getAnnotationFontStyle()

Returns the CSS font-style in which the text of this annotation will be rendered.

Returns:

the font-style used by this annotation (italic, normal, etc.)

See Also:

setAnnotationFontStyle

getAnnotationFontSize

public int getAnnotationFontSize()

Returns the font size of this point's annotation (text label), in pixels.

Returns:

the font size of this point's annotation.

See Also:

setAnnotationFontSize

getAnnotationLocation

public GChart.AnnotationLocation getAnnotationLocation()

Returns the previously specified location, relative to the symbol representing the point, of the annotation (text label) associated with this point.

Returns:

relative location of the point's annotation

See Also:

setAnnotationLocation

getAnnotationText

public java.lang.String getAnnotationText()

Returns the text of this point's annotation.

Returns:

the text of the annotation, or null if this point lacks an annotation.

See Also:

setAnnotationText

getAnnotationWidget

public com.google.gwt.user.client.ui.Widget getAnnotationWidget()

Returns the widget reference that defines this point's annotation as previously specified by setAnnotationWidget. Returns null if the annotation has not yet been specified, or if it was defined via setAnnotationText.

Returns:

reference to the widget defining this point's annotation, or null if none.

See Also:

setAnnotationWidget, setAnnotationText

getAnnotationVisible

public boolean getAnnotationVisible()

Returns true is the point's annotation is visible, false otherwise

Returns:

if the a annotation defined for this point will be visible or not after the next update.

See Also:

setAnnotationVisible

getAnnotationXShift

public int getAnnotationXShift()

Returns the distance, in pixels, that this annotation will be shifted along the x-axis from it's default location.

Returns:

amount annotation will be shifted along the x-axis, in pixels.

See Also:

setAnnotationXShift

getAnnotationYShift

public int getAnnotationYShift()

Returns the distance, in pixels, that this annotation will be shifted along the y-axis from it's default location.

Returns:

amount annotation will be shifted along the y-axis, in pixels.

See Also:

setAnnotationYShift

getParent

public GChart.Curve getParent()

Returns the Curve that this point was added to.

Returns:

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

getX

public double getX()

Returns the x-coordinate of this point in "model units" (arbitrary, application-specific, units).

Returns:

the x-coordinate, in model units

See Also:

setX, setY, getY

getY

public double getY()

Returns the y-coordinate of this point in "model units" (arbitrary, application-specific, units).

Returns:

the y-coordinate, in model units

See Also:

getX, setX, setY

setAnnotationFontWeight

public void setAnnotationFontWeight(java.lang.String cssWeight)

Specifies the weight of the font that will be used to render the text of this point's annotation.

Parameters:

cssWeight - A standard CSS font-weight specification such as normal, bold, bolder, lighter, 100, 200, ... 900, or inherit

See Also:

getAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontStyle, setAnnotationFontSize, setAnnotationXShift, setAnnotationYShift, setAnnotationText, setAnnotationVisible

setAnnotationFontColor

public void setAnnotationFontColor(java.lang.String cssColor)

Specifies the color of the annotation's font.

For more information on standard CSS color specifications see the discussion in Symbol.setBackgroundColor.

Parameters:

cssColor - color of the font used to display this point's annotation message.

See Also:

getAnnotationFontColor, setAnnotationFontWeight, setAnnotationFontStyle, setAnnotationFontSize, setAnnotationXShift, setAnnotationYShift, setAnnotationText, setAnnotationVisible

setAnnotationFontStyle

public void setAnnotationFontStyle(java.lang.String cssStyle)

Specifies the CSS font-style used by this point's annotation message.

Parameters:

cssStyle - any valid CSS font-style, namely, normal, italic, oblique, or inherit.

See Also:

getAnnotationFontStyle, setAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontSize, setAnnotationXShift, setAnnotationYShift, setAnnotationText, setAnnotationVisible

setAnnotationFontSize

public void setAnnotationFontSize(int fontSize)

Specifies the font size of this point's annotation, in pixels.

Parameters:

fontSize - the font size of this point's annotation, in pixels.

See Also:

getAnnotationFontSize, setAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontStyle, setAnnotationXShift, setAnnotationYShift, setAnnotationText, setAnnotationVisible

setAnnotationLocation

public void setAnnotationLocation(GChart.AnnotationLocation annotationLocation)

Specifies the location, relative to this point's symbol, of this point's annotation (text label).

You can further adjust the position of a point's annotation by specifying non-zero positional shifts via the setAnnotationXShift and setAnnotationYShift methods.

Parameters:

annotationLocation - the relative location of the annotation

See Also:

getAnnotationLocation, setAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontStyle, setAnnotationFontSize, setAnnotationText, setAnnotationXShift, setAnnotationYShift, setAnnotationVisible

setAnnotationText

public void setAnnotationText(java.lang.String annotationText,
                              int widthUpperBound,
                              int heightUpperBound)

Specifies the text of this point's annotation (label).

By default text is plain text, though you can change the size, weight, style, and color of the text via the setAnnotationFont* family of methods.

To use HTML, your text must begin with <html> (otherwise, GChart will treat it as plain text). Note that the leading <html> is stripped off by GChart before your HTML gets to the browser. Since it's just a flag for GChart, not a real HTML tag, you should not use a closing </html> at the end.

The idea for adding HTML support (only plain text was supported originally) came from this GWT forum post by Malcolm Gorman. The current HTML support (and, it's natural extension, Widget support) in tick labels and annotations, which seems so obvious in hindsight, might never have been added had it not been for this post. Thanks!

How to use the width and height upperbounds:

In most cases, you can safely ignore these two parameters, simply calling the 1-arg convenience method and getting GChart to estimate them for you.

The width and height upperbounds define an invisible bounding box (a 1x1 GWT Grid, actualy) that is used to properly align and center your annotation.

Annotations can become misaligned if, say, due to the user zooming up their font size, an annotation's size exceeds these upperbounds. This misalignment problem can be fixed by specifying a larger width and/or height upperbound. But, larger upperbounds slow chart updates a bit. The defaults try to balance the performance and alignment tradeoff.

Parameters:

annotationText - the text or (<html> prefixed) HTML of this point's annotation, or null to remove all annotation.

widthUpperBound - an upper bound on the width of the text or HTML, in pixels. Use GChart.NAI to get GChart to estimate this width using a heuristic that works fine most of the time.

heightUpperBound - an upper bound on the height of the text or HTML, in pixels. Use GChart.NAI to get GChart to estimate this height using a heuristic that works fine most of the time.

See Also:

getAnnotationText, setAnnotationText(String), setAnnotationLocation, setAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontStyle, setAnnotationFontSize, setAnnotationXShift, setAnnotationYShift, setAnnotationVisible, addTick

setAnnotationText

public void setAnnotationText(java.lang.String annotationText)

Sets the text of an annotation.

This is a convenience method equivalent to setAnnotationText(annotationText, GChart.NAI, GChart.NAI). See that method for further details.

Parameters:

annotationText - the text or (<html>-prefixed) HTML of this point's annotation, or null to remove all annotation.

See Also:

setAnnotationText(String,int,int)

setAnnotationWidget

public void setAnnotationWidget(com.google.gwt.user.client.ui.Widget annotationWidget,
                                int widthUpperBound,
                                int heightUpperBound)

Specifies a widget defining this point's annotation

This method is similar to setAnnotationText except that it uses a widget, rather than a string to define this point's annotation. Although the string based method is faster on first chart rendering, and uses less memory, the widget-based method allows you to change the annotation independently of the chart--potentially bypassing (or at least speeding up) expensive chart updates later on.

You might use a widget-based annotation to pop-up a message whenever the user clicks on a button underneath a particular data point on the chart, to include a small GWT Grid as a table embedded in the upper left hand corner of the chart, to trigger mouse-over events when the user hovers over a transparent image-based annotation centered on a particular point, etc.

Tip:If you need to instrument a chart using widgets precisely positioned on the chart, but not associated with any visible curve, add a curve just to hold these annotations, with one point per annotation, and set that curve's symbol type to SymbolType.NONE.

Parameters:

annotationWidget - the GWT Widget that defines this point's annotation.

widthUpperBound - an upper bound on the width of the Widget, in pixels. If this and the next parameter are omitted, GChart will use DEFAULT_WIDGET_WIDTH_UPPERBOUND.

heightUpperBound - an upper bound on the height of the Widget, in pixels. If this and the previous parameter are omitted, GChart will use DEFAULT_WIDGET_HEIGHT_UPPERBOUND

See Also:

getAnnotationWidget, setAnnotationText(String,int,int), setAnnotationWidget(Widget), DEFAULT_WIDGET_HEIGHT_UPPERBOUND, DEFAULT_WIDGET_WIDTH_UPPERBOUND, SymbolType.NONE

setAnnotationWidget

public void setAnnotationWidget(com.google.gwt.user.client.ui.Widget annotationWidget)

Specifies a widget defining this point's annotation.

A convenience method equivalent to setAnnotationWidget(annotationWidget, DEFAULT_WIDGET_WIDTH_UPPERBOUND, DEFAULT_WIDGET_HEIGHT_UPPERBOUND)

Parameters:

annotationWidget - the GWT Widget that defines this point's annotation.

See Also:

setAnnotationWidget(Widget,int,int), DEFAULT_WIDGET_HEIGHT_UPPERBOUND, DEFAULT_WIDGET_WIDTH_UPPERBOUND

setAnnotationVisible

public void setAnnotationVisible(boolean isVisible)

Specifies if this point's annotation (label) is visible or not.

Parameters:

isVisible - use true to make the annotation visible, or false to hide it.

See Also:

getAnnotationVisible, setAnnotationLocation, setAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontStyle, setAnnotationFontSize, setAnnotationXShift, setAnnotationYShift, setAnnotationText

setAnnotationXShift

public void setAnnotationXShift(int xShift)

Specifies the number of pixels (along the x-axis) to move this point's annotation from its default, AnnotationLocation-defined, position. Negative values move the annotation in the negative x direction.

For example, with the default xShift of 0, annotations with an AnnotationLocation of EAST will have their left edges flush against the right edge of, say, a box symbol representing the annotated point. You could use an xShift setting of 10 to move the annotation 10 pixels to the right and thus introduce some space between the annotation and the box.

Special convention for pie slices: Points on curves whose symbols represent pie slices always have the positive x-axis associated with the shifts specified by this method aligned with the outward-pointing pie radius that bisects the pie slice. This convention makes it easy to move pie slice annotations radially outward (via xShift > 0) or radially inward (via xShift < 0). For those rare situations where you may need to move a pie annotation perpendicularly to this radius, use setAnnotationYShift.

Parameters:

xShift - number of pixels to move annotation along the x axis from it's default, AnnotationLocation-defined, location.

See Also:

setAnnotationYShift, setAnnotationLocation, setAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontStyle, setAnnotationFontSize, setAnnotationText, setAnnotationVisible, getAnnotationXShift

setAnnotationYShift

public void setAnnotationYShift(int yShift)

Specifies the number of pixels (along the y-axis) to move this point's annotation from its default, AnnotationLocation-defined, position. Negative values move the annotation in the negative y direction.

For example, with the default yShift of 0, annotations with an AnnotationLocation of SOUTH will have their top edges flush against the bottom edge of, say, a box symbol representing the annotated point. You could use a yShift setting of -10 to move the annotation down 10 pixels and thus introduce some spacing between the annotation and the box.

Special convention for pie slices: The positive y-axis for pie slices always points one 90 degree counter-clockwise rotation from the direction of the outward-pointing pie radius that bisects the pie slice. This convention means that yShift moves pie slice annotations along a line perpendicular to this bisecting pie radius. Use the companion method setAnnotationXShift for the more common operation of moving the annotation along this bisecting radius.

Parameters:

yShift - number of pixels to move annotation along the y-axis from it's default, AnnotationLocation-defined, location.

See Also:

setAnnotationXShift, setAnnotationLocation, setAnnotationFontWeight, setAnnotationFontColor, setAnnotationFontStyle, setAnnotationFontSize, setAnnotationText, setAnnotationVisible, getAnnotationXShift

setX

public void setX(double x)

Defines the x-coordinate of this point in "model units" (arbitrary, application-specific, units mapped to the horizontal dimension of the plot area).

Double.NaN, Double.MAX_VALUE, and -Double.MAX_VALUE have special meanings. See the addPoint method for details.

Parameters:

x - the x-coordinate of the point in model units.

See Also:

getX, setY, getY, addPoint

setY

public void setY(double y)

Defines the y-coordinate of this point in "model units" (arbitrary, application-specific, units mapped to the vertical dimension of the plot area).

Double.NaN, Double.MAX_VALUE, and -Double.MAX_VALUE have special meanings. See the addPoint method for details.

Parameters:

y - the y-coordinate of the point in model units.

See Also:

getX, setX, getY, addPoint