com.googlecode.gchart.client
Class GChart.Axis

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

Direct Known Subclasses:

GChart.XAxis, GChart.Y2Axis, GChart.YAxis

Enclosing class:

GChart

public abstract class GChart.Axis
extends java.lang.Object

Represents an axis of the chart, for example, the x, y, or y2 axis. An axis consists of the axis itself, along with its tick marks, tick labels and gridlines.

See Also:

XAxis, YAxis, Y2Axis, getXAxis, getYAxis, getY2Axis

Constructor Summary

GChart.Axis()

Method Summary

void	addTick(double tickPosition) Adds a tick on this axis at the specified position.
void	addTick(double tickPosition, java.lang.String tickLabel) Adds a tick at the specified position with the specified label on this axis.
void	addTick(double tickPosition, java.lang.String tickLabel, int widthUpperBound, int heightUpperBound) Adds a tick at the specified position with the specified label on this axis, whose width and height are within the specified upper-bounds.
void	addTick(double tickPosition, com.google.gwt.user.client.ui.Widget tickWidget) Adds a Widget-defined tick label at the specified position.
void	addTick(double tickPosition, com.google.gwt.user.client.ui.Widget tickWidget, int widthUpperBound, int heightUpperBound) Adds a widget-defined tick label at the specified position, whose width and height are within the specified upper-bounds.
void	clearTicks() Removes all ticks from this axis.
abstract double	clientToModel(int clientCoordinate) Converts a pixel, client-window coordinate position along this axis into the model units associated with this axis.
java.lang.String	formatAsTickLabel(double value) Applies this axis' tick label format to format a given value.
java.lang.String	formatNumberAsTickLabel(double value) Deprecated. Equivalent to the better-named formatAsTickLabel.
com.google.gwt.user.client.ui.Widget	getAxisLabel() Returns the previously specified label of this axis.
int	getAxisLabelThickness() Returns the thickness of the axis-label-holding region adjacent to the region allocated for this axis' tick labels.
double	getAxisMax() Returns the maximum value displayed on this axis.
double	getAxisMin() Returns the minimum value displayed on this axis.
boolean	getAxisVisible() Is axis line visible on the chart? Note that this property only determines the visibility of the axis line itself.
abstract double	getDataMax() Returns the maximum data value associated with values represented on this axis.
abstract double	getDataMin() Returns the minimum data value associated with values represented on this axis.
boolean	getHasGridlines() Returns the gridline setting previously made with setHasGridlines.
abstract double	getMouseCoordinate() Returns the coordinate along this axis that is associated with the last "GChart-tracked" mouse location.
int	getNCurvesVisibleOnAxis() Returns the number of visible curves displayed on this axis.
int	getTickCount() Returns the number of ticks on this axis.
java.lang.String	getTickLabelFontColor() Returns the color of the font used to display the text of the tick labels on this axis.
int	getTickLabelFontSize() Returns the CSS font size, in pixels, used for tick labels on this axis.
java.lang.String	getTickLabelFontStyle() Returns the font-style of the font used to render tick labels on this axis (typically either "italic" or "normal")
java.lang.String	getTickLabelFontWeight() Returns the CSS font-weight specification to be used by this axis' tick labels.
java.lang.String	getTickLabelFormat() Returns the tick label numeric format string for this axis.
int	getTickLabelPadding() Returns the amount of padding (blank space) between the ticks and their labels.
int	getTickLabelThickness() Returns the thickness of the band adjacent to this axis that GChart will allocate to hold this axis' tick labels.
int	getTickLength() Returns the length of ticks for this axis.
GChart.TickLocation	getTickLocation() Returns relative location of ticks on this axis.
int	getTickSpace() Returns the amount of space along the axis reserved for the tick marks themselves, in pixels.
int	getTicksPerGridline() Returns the ratio of the number of ticks to the number of ticks that have an associated gridline.
int	getTicksPerLabel() Returns the ratio of the number of ticks to the number of labeled ticks.
int	getTickThickness() Returns the thickness of ticks for this axis.
abstract double	modelToClient(double modelCoordinate) Converts a coordinate position in the model units associated with this axis into a corresponding coordinate position expressed in standard GWT client-window pixel coordinates.
abstract double	modelToPixel(double modelCoordinate) Converts a coordinate position in the model units associated with this axis into a corresponding coordinate position expressed in GChart's decorated chart pixel coordinates.
abstract double	modelToPlotAreaPixel(double modelCoordinate) Converts a coordinate position in the model units associated with this axis into a corresponding coordinate position expressed in GChart's plot area pixel coordinates.
abstract double	pixelToModel(int pixelCoordinate) Converts a coordinate position in GChart's decorated chart pixel coordinates into the model units associated with this axis.
abstract double	plotAreaPixelToModel(int pixelCoordinate) Converts a coordinate position in GChart's plot area pixel coordinates into the model units associated with this axis.
void	setAxisLabel(java.lang.String html) Convenience method equivalent to setAxisLabel(new HTML(html))
void	setAxisLabel(com.google.gwt.user.client.ui.Widget axisLabel) Specifies the label of this axis.
void	setAxisLabelThickness(int thickness) Sets the thickness of the axis-label-holding region adjacent to the region allocated for tick labels.
void	setAxisMax(double max) Specifies the maximum value visible on this axis.
void	setAxisMin(double min) Specifies the minimum value of this axis.
void	setAxisVisible(boolean axisVisible) Defines if this axis is visible.
void	setHasGridlines(boolean hasGridlines) Specifies if this axis should have gridlines.
void	setTickCount(int tickCount) Sets the number of ticks to be placed on this axis.
void	setTickLabelFontColor(java.lang.String cssColor) Specifies the color of the font used to render tick labels for this axis.
void	setTickLabelFontSize(int tickLabelFontSize) Sets the CSS font size for tick labels on this axis, in pixels.
void	setTickLabelFontStyle(java.lang.String cssStyle) Specifies the CSS font-style of this axis' tick labels.
void	setTickLabelFontWeight(java.lang.String cssWeight) Specifies the weight of the font used in this axis' tick labels.
void	setTickLabelFormat(java.lang.String format) Specifies a format string to be used in converting the numeric values associated with each tick on this axis into tick labels.
void	setTickLabelPadding(int tickLabelPadding) Specifies the number of pixels of padding (blank space) between the tick marks and their labels.
void	setTickLabelThickness(int tickLabelThickness) Specifies the thickness of the region adjacent to this axis that GChart will reserve for purposes of holding this axis' tick labels.
abstract void	setTickLength(int tickLength) Sets this axis' tick length.
void	setTickLocation(GChart.TickLocation tickLocation) Specifies the location of the tick marks relative to this axis, namely, if tick marks are outside, inside, or centered on this axis.
void	setTicksPerGridline(int ticksPerGridline) Specifies the ratio of the number of tick marks on the axis, to the number of gridlines on the axis.
void	setTicksPerLabel(int ticksPerLabel) Specifies the ratio of the number of tick marks on the axis, to the number of labeled tick marks on the axis.
abstract void	setTickThickness(int tickThickness) Sets this axis' tick thickness.

Methods inherited from class java.lang.Object

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

Constructor Detail

GChart.Axis

public GChart.Axis()

Method Detail

addTick

public void addTick(double tickPosition)

Adds a tick on this axis at the specified position. Note that explicitly adding a single tick via this method will eliminate any implicitly generated ticks associated with the setTickCount method.

The label associated with this tick will be generated by applying the format specified via setTickLabelFormat to the specified position.

This is a convenience method equivalent to addTick(tickPosition, thisAxis.formatAsTickLabel(tickPosition), GChart.NAI, GChart.NAI). See addTick(tickPosition,tickLabel,widthUpperBound,heightUpperBound) for details.

Parameters:

tickPosition - the position, in model units, along this axis at which this tick is displayed. For example, if the axis range goes from 0 to 100, a tick at position 50 would appear in the middle of the axis.

See Also:

clearTicks, addTick(double,String), addTick(double,String,int,int), addTick(double,Widget,int,int), formatAsTickLabel, setTickCount, setTickLabelFormat, setTickLabelFontStyle, setTickLabelFontColor, setTickLabelFontWeight, setTickLabelFontSize

addTick

public void addTick(double tickPosition,
                    java.lang.String tickLabel,
                    int widthUpperBound,
                    int heightUpperBound)

Adds a tick at the specified position with the specified label on this axis, whose width and height are within the specified upper-bounds.

Note that explicitly adding a single tick via this method will eliminate any auto-generated ticks associated with the setTickCount method.

Use this method to specify unusually spaced tick marks with labels that do not directly reflect the position (for example, for a logarithmic axis, or for a bar chart with special keyword-type labels, or a time axis that places date and time on two separate lines).

Parameters:

tickPosition - the position, in model units, along this axis at which the tick is displayed. For example, if the axis range goes from 0 to 1, a tick at position 0.5 would appear in the middle of the axis.

tickLabel - the label for this tick. HTML is supported in tick labels, but it must be prefixed by <html>. See the setAnnotationText method for more information.

widthUpperBound - an upper bound on the width of the text or HTML, in pixels. Use GChart.NAI to get GChart to estimate this width for you. See the setAnnotationText method for more information.

heightUpperBound - an upper bound on the height of the text or HTML, in pixels. Use GChart.NAI to get GChart to estimate this height for you. See the setAnnotationText method for more information.

See Also:

clearTicks, addTick(double), addTick(double,String), addTick(double,Widget,int,int), setTickCount, setTickLabelFormat, setTickLabelFontSize, setTickLabelFontStyle, setTickLabelFontColor, setTickLabelFontWeight, setAnnotationText, setAnnotationWidget

addTick

public void addTick(double tickPosition,
                    java.lang.String tickLabel)

Adds a tick at the specified position with the specified label on this axis.

This is a convenience method equivalent to addTick(tickPosition, tickLabel, GChart.NAI, GChart.NAI). Most applications can usually just use this convenience method. See addTick(tickPosition,tickLabel, widthUpperBound,heightUpperBound) for the fine print.

Parameters:

tickPosition - the position, in model units, along this axis at which the tick is displayed.

tickLabel - the plain text or (<html>-prefixed) HTML defining the tick's label.

See Also:

addTick(double,String,int,int), addTick(double,Widget)

addTick

public void addTick(double tickPosition,
                    com.google.gwt.user.client.ui.Widget tickWidget,
                    int widthUpperBound,
                    int heightUpperBound)

Adds a widget-defined tick label at the specified position, whose width and height are within the specified upper-bounds.

This method is similar to addTick(double,String,int,int) except that it uses a widget, rather than a string, to define the tick's label. Although the string-based method is faster on first chart rendering, and uses less memory, the widget-based method allows you to change the label independently of the chart--potentially bypassing (or speeding up) expensive chart updates later on.

You might use a widget-based tick label to pop up a dialog that allows the user to edit the parameters defining the axis (min, max, etc.) whenever they click on one of the tick labels on that axis, to define hovertext that appears when the user mouses over a tick label, to use images for your tick labels, etc.

Parameters:

tickPosition - the position, in model units, along this axis at which the tick is displayed. For example, if the axis range goes from 0 to 1, a tick at position 0.5 would appear in the middle of the axis.

tickWidget - the label for this tick, as defined by any GWT Widget.

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:

addTick(double,Widget), addTick(double,String,int,int), setAnnotationWidget, DEFAULT_WIDGET_WIDTH_UPPERBOUND, DEFAULT_WIDGET_HEIGHT_UPPERBOUND

addTick

public void addTick(double tickPosition,
                    com.google.gwt.user.client.ui.Widget tickWidget)

Adds a Widget-defined tick label at the specified position. Convenience method equivalent to addTick(tickPosition, tickWidget, DEFAULT_WIDGET_WIDTH_UPPERBOUND, DEFAULT_WIDGET_HEIGHT_UPPERBOUND).

Parameters:

tickPosition - the position, in model units, along this axis at which the tick is displayed. For example, if the axis range goes from 0 to 1, a tick at position 0.5 would appear in the middle of the axis.

tickWidget - the label for this tick, as defined by any GWT Widget.

See Also:

addTick(double,Widget,int,int)

clearTicks

public void clearTicks()

Removes all ticks from this axis. Specifically, erases any ticks that were explicitly specified via addTick, and also sets the tick count to 0.

See Also:

setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int)

clientToModel

public abstract double clientToModel(int clientCoordinate)

Converts a pixel, client-window coordinate position along this axis into the model units associated with this axis.

For example, if the client coordinate associated with this axis' midpoint were passed to this method, it would return (getAxisMin() + getAxisMax())/2.0.

Note that the client/model coordinate mapping used is as of the last update. Before the first update, this method returns GChart.NaN. This method also invokes either getAbsoluteTop (for the y or y2 axis) or getAbsoluteLeft (for the x axis), and these GWT methods return 0 if the chart isn't actually rendered within the browser. So, results likely won't be useful to you until after the page containing your chart becomes visible to the user. Since most applications are expected to invoke this method in response to the user mousing over the page, these requirements should usually be satisfied.

Saurabh Hirani in this GWT Forum post and in GChart issue #22 most recently suggested the need for client to model coordinate mapping. Client to model conversion was requested earlier in GChart issue #9 from yoxel.com.

Parameters:

clientCoordinate - a pixel-based coordinate that defines the dimension associated with this axis in the standard client window coordinates of GWT.

Returns:

the location defined by the client-coordinate argument, but converted into the model units associated with this axis.

See Also:

getMouseCoordinate, modelToClient, pixelToModel, modelToPixel

formatAsTickLabel

public java.lang.String formatAsTickLabel(double value)

Applies this axis' tick label format to format a given value.

Returns:

the value formated as per this axis' currently specified tick label format.

See Also:

setTickLabelFormat

formatNumberAsTickLabel

public java.lang.String formatNumberAsTickLabel(double value)

Deprecated. Equivalent to the better-named formatAsTickLabel.

See Also:

formatAsTickLabel

getAxisLabel

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

Returns the previously specified label of this axis.

Returns:

the Widget used as the label of this axis

See Also:

setAxisLabel

getAxisLabelThickness

public int getAxisLabelThickness()

Returns the thickness of the axis-label-holding region adjacent to the region allocated for this axis' tick labels.

Note that if the axis label is null (the default) then this method always returns 0, since in that case no rectangular region will be allocated for the axis label.

Returns:

the thickness of the axis-label-holding region, in pixels.

See Also:

setAxisLabelThickness

getAxisMax

public double getAxisMax()

Returns the maximum value displayed on this axis. If the explicitly specified maximum value is undefined (Double.NaN) the maximum value returned by this function is calculated as the maximum of all of the values either displayed on this axis via points on a curve, or explicitly specified via tick positions.

Returns:

maximum value visible on this axis, in "model units" (arbitrary, application-specific, units)

See Also:

setAxisMax, getDataMin, getDataMax

getAxisMin

public double getAxisMin()

Returns the minimum value displayed on this axis. If the minimum value is undefined (Double.NaN) the minimum value returned by this function is the minimum of all of the values either displayed on this axis via points on a curve, or explicitly specified via tick positions.

Returns:

minimum value visible on this axis, in "model units" (arbitrary, application-specific, units)

See Also:

setAxisMin

getAxisVisible

public boolean getAxisVisible()

Is axis line visible on the chart? Note that this property only determines the visibility of the axis line itself. It does not control the visibility of the tick marks or tick labels along this axis.

Returns:

true if the axis line is visible, false otherwise.

See Also:

setAxisVisible

getDataMax

public abstract double getDataMax()

Returns the maximum data value associated with values represented on this axis. For example, for the left y-axis, this would be the largest y-value of all points contained in curves that are displayed on the left y-axis.

Returns:

the maximum value associated with values mapped onto this axis.

See Also:

getDataMin, getAxisMax, getAxisMin

getDataMin

public abstract double getDataMin()

Returns the minimum data value associated with values represented on this axis. For example, for the left y-axis, this would be the smallest y-value of all points contained in curves that are displayed on the left y-axis.

Returns:

the minimum value associated with values mapped onto this axis.

See Also:

getDataMax, getAxisMax, getAxisMax

getHasGridlines

public boolean getHasGridlines()

Returns the gridline setting previously made with setHasGridlines.

Returns:

true if gridlines have been enabled, false if not.

See Also:

setHasGridlines

getMouseCoordinate

public abstract double getMouseCoordinate()

Returns the coordinate along this axis that is associated with the last "GChart-tracked" mouse location.

The coordinate returned is in the "scale" associated with the axis. For example, if the axis mininum is 0 and the maximum is 100, and the mouse is at the axis midpoint, this method would return 50.

The main intended use for this method is to allow you to create points that, if they have x and y coordinates defined by calling this method on appropriate axes, will be positioned on the chart at the last GChart-tracked mouse location.

As the user moves their mouse over the chart, GChart watches those mouse moves and updates it's currently "tracked" mouse location. That internally maintained position is the basis for the value returned by this method. Note that the actual, physical, mouse cursor position could differ from this GChart-tracked position because:

1. The mouse has moved off the chart, and it's GChart-tracked location has become undefined (this method returns Double.NaN in that case)
2. You have invoked setHoverTouchingEnabled(false) which means that mouse moves are no longer tracked, so the last GChart-tracked mouse location will be the last position that the user clicked on.
3. You have popped up a modal dialog that "eats" mouse moves so GChart no longer sees them. In that case, the GChart-tracked mouse location is the location the mouse was at when the modal dialog popped up.
4. You are mousing over the opened hover widget (popup). Note that, to prevent the user from accidentally "touching" nearby points while interacting with the opened hover widget, GChart ignores mouse moves over the opened hover widget.
5. Other, similar, reasons.

In other words, this routine tells you where, for hit testing and hover selection feedback purposes, GChart considers the mouse to be, not the actual physical location of the mouse. Despite the potential for differences, in most cases, with the default setting of setHoverTouchingEnabled(true), and when you are not over the opened hover widget, you can use the value returned by this method as if it represented the physical mouse location.

For an example that uses this method to create points at the current mouse location within a very simple line chart editor, see the Chart Gallery's GChartExample22a.

Returns:

the coordinate, projected along this axis, in the scale defined by this axis, representing the position GChart has currently "tracked" the mouse to, or Double.NaN if GChart has tracked the mouse right off the edge of the chart.

See Also:

clientToModel, modelToClient, pixelToModel, modelToPixel, setHoverTouchingEnabled

getNCurvesVisibleOnAxis

public int getNCurvesVisibleOnAxis()

Returns the number of visible curves displayed on this axis.

Returns:

the number of visible curves on this axis, or 0 if there are no visible curves on this axis.

See Also:

setVisible

getTickCount

public int getTickCount()

Returns the number of ticks on this axis.

Returns:

the number of ticks on this axis.

See Also:

setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int), clearTicks

getTickLabelFontWeight

public java.lang.String getTickLabelFontWeight()

Returns the CSS font-weight specification to be used by this axis' tick labels.

Returns:

font-weight of this axis' tick labels

See Also:

setTickLabelFontWeight

getTickLabelFontColor

public java.lang.String getTickLabelFontColor()

Returns the color of the font used to display the text of the tick labels on this axis.

Returns:

CSS color string defining the color of the text of the tick labels for this axis.

See Also:

setTickLabelFontColor, DEFAULT_TICK_LABEL_FONT_COLOR

getTickLabelFontStyle

public java.lang.String getTickLabelFontStyle()

Returns the font-style of the font used to render tick labels on this axis (typically either "italic" or "normal")

Returns:

the CSS font-style in which tick labels of this axis are rendered.

See Also:

setTickLabelFontStyle

getTickLabelFontSize

public int getTickLabelFontSize()

Returns the CSS font size, in pixels, used for tick labels on this axis.

Returns:

the tick label font size in pixels

See Also:

setTickLabelFontSize

getTickLabelFormat

public java.lang.String getTickLabelFormat()

Returns the tick label numeric format string for this axis.

Returns:

numeric format used to generate tick labels.

See Also:

setTickLabelFormat

getTickLabelPadding

public int getTickLabelPadding()

Returns the amount of padding (blank space) between the ticks and their labels.

Returns:

amount of padding between ticks and their labels, in pixels.

See Also:

setTickLabelPadding

getTickLabelThickness

public int getTickLabelThickness()

Returns the thickness of the band adjacent to this axis that GChart will allocate to hold this axis' tick labels.

Returns:

width of band, in pixels, GChart will reserve for this axis' tick labels.

See Also:

setTickLabelThickness

getTicksPerGridline

public int getTicksPerGridline()

Returns the ratio of the number of ticks to the number of ticks that have an associated gridline.

Returns:

number of ticks per gridline for this axis

See Also:

setTicksPerGridline

getTicksPerLabel

public int getTicksPerLabel()

Returns the ratio of the number of ticks to the number of labeled ticks.

Returns:

number of ticks per label.

See Also:

setTicksPerLabel

getTickLength

public int getTickLength()

Returns the length of ticks for this axis.

Returns:

the length of this axis' ticks, in pixels.

See Also:

setTickLength

getTickLocation

public GChart.TickLocation getTickLocation()

Returns relative location of ticks on this axis.

Returns:

TickLocation.INSIDE, TickLocation.OUTSIDE, or TickLocation.CENTERED

See Also:

setTickLocation

getTickSpace

public int getTickSpace()

Returns the amount of space along the axis reserved for the tick marks themselves, in pixels.

This equals the length of the part of the tick that is outside of the plot area.

Returns:

the space GChart will allocate just outside the axis to hold any tick marks.

See Also:

setTickLength, setTickLabelPadding, setTickLocation

getTickThickness

public int getTickThickness()

Returns the thickness of ticks for this axis.

Returns:

the thickness of this axis' ticks, in pixels.

See Also:

setTickThickness, getTickLength

modelToClient

public abstract double modelToClient(double modelCoordinate)

Converts a coordinate position in the model units associated with this axis into a corresponding coordinate position expressed in standard GWT client-window pixel coordinates.

For example, consider a completely undecorated chart (no axes, tick labels, legend keys, etc.) that exactly fills a 1000px wide client window, and whose x-axis min and max are 0 and 100. Then getXAxis().modelToClient(50) would return 500.

Note that the client/model coordinate mapping used is as of the last update. Before the first update, this method returns GChart.NaN. This method also invokes either getAbsoluteTop (for the y or y2 axis) or getAbsoluteLeft (for the x axis), and these GWT methods return 0 if the chart isn't actually rendered within the browser. So, results likely won't be useful to you until after the page containing your chart becomes visible to the user. Since most applications are expected to invoke this method in response to the user mousing over the page, these requirements should usually be satisfied.

Parameters:

modelCoordinate - the position along this axis defined in the model units associated with this axis.

Returns:

a pixel-based coordinate that defines the position associated with the argument in the standard pixel, client window, coordinates of GWT.

See Also:

getMouseCoordinate, clientToModel, pixelToModel, modelToPixel

modelToPixel

public abstract double modelToPixel(double modelCoordinate)

Converts a coordinate position in the model units associated with this axis into a corresponding coordinate position expressed in GChart's decorated chart pixel coordinates.

These coordinates have their origin at the upper left corner of the decorated GChart, and x pixel-coordinates that increase as you move right, and y pixel-coordinates that increase as you move down. They are related to GWT's standard client window coordinates via the following equations:

   xClient = plotPanel.getAbsoluteLeft()
             - Window.getScrollLeft()
             + xPixel;
   yClient = plotPanel.getAbsoluteTop()
             - Window.getScrollTop()
             + yPixel;
 

In the above plotPanel is an internal AbsolutePanel GChart creates to hold the entire, decorated, chart. Apart from borders and such applied to the GChart as a whole, its absolute top and left positions should be the same as those of the GChart itself.

Tip: In applications that continuously track mouse moves over the chart, and where absolute and scroll positions cannot change, you can gain a significant performance boost by computing the difference between pixel and client coordinates once (modelToPixel(axisMin)-modelToClient(axisMin)) and then adding that difference to the client coordinates to get the pixel coordinates, and then using pixelToModel, instead of using clientToModel directly, which must repeatedly call GWT's scroll and absolute position methods.

For example, for a completely undecorated chart (no tick labels, legend keys, etc.) the plot area takes up the entire chart. In that case, if the pixel units of the plot area range from 0...100 along this axis, and the model coordinates range from 0...10 along this axis, then modelToPixel(modelCoordinate) returns 10*modelCoordinate.

The model/pixel mapping is as of the last update; this method returns Double.NaN before the first update. Note that, unlike clientToModel and modelToClient, the GChart does not need to be actually rendered within the browser for you to use this method--a call to update is sufficient.

Tip: If you need to access this mapping before the first real update, you can explicitly specify the min and max of this axis via setAxisMin and setAxisMax, and then call update before adding any curves to the chart (which, since the chart is empty, should be very fast). This approach will allow you to convert between model and pixel coordinates before the first real update, and before the chart is rendered in the browser.

Parameters:

modelCoordinate - a position on this axis expressed in the model units associated with this axis.

Returns:

the distance, in pixels, from the left edge (for the x axis) or top edge (for the y or y2 axis) of the decorated chart to the given position on this axis.

See Also:

getMouseCoordinate, clientToModel, modelToClient, modelToClient, pixelToModel

modelToPlotAreaPixel

public abstract double modelToPlotAreaPixel(double modelCoordinate)

Converts a coordinate position in the model units associated with this axis into a corresponding coordinate position expressed in GChart's plot area pixel coordinates.

These coordinates have their origin at the upper left corner of the plot area, and x pixel-coordinates that increase as you move right, and y pixel-coordinates that increase as you move down.

The plot area is the rectangular region bounded by the chart's axes, and with a size specified via setChartSize, where the chart's curves are typically displayed.

Apart from a shift in the origin of the pixel coordinates used, this method works just like modelToPixel; see that method for additional details, tips, and restrictions.

Parameters:

modelCoordinate - a position on this axis expressed in the model units associated with this axis.

Returns:

the distance, in pixels, from the left edge (for the x axis) or top edge (for the y or y2 axis) of the plot area to the given position on this axis.

See Also:

getMouseCoordinate, plotAreaPixelToModel, modelToPixel, setChartSize

pixelToModel

public abstract double pixelToModel(int pixelCoordinate)

Converts a coordinate position in GChart's decorated chart pixel coordinates into the model units associated with this axis.

GChart's decorated chart pixel coordinates have their origin at the upper left corner of the decorated GChart, and x pixel-coordinates that increase as you move right, and y pixel-coordinates that increase as you move down. They are related to GWT's standard client window coordinates via the following equations:

   xClient = plotPanel.getAbsoluteLeft()
             - Window.getScrollLeft()
             + xPixel;
   yClient = plotPanel.getAbsoluteTop()
             - Window.getScrollTop()
             + yPixel;
 

In the above plotPanel is an internal AbsolutePanel GChart creates to hold the entire, decorated, chart. Apart from borders and such applied to the GChart as a whole, its absolute top and left positions should be the same as those of the GChart itself.

For example, for a completely undecorated chart (no tick labels, legend keys, etc.) the plot area takes up the entire chart. In that case, if the pixel units of the plot area range from 0...100 along this axis, and the model coordinates range from 0...10 along this axis, then pixelToModel(pixelCoordinate) returns pixelCoordinate/10..

The model/pixel mapping is as of the last update; this method returns Double.NaN before the first update. Note that, unlike clientToModel and modelToClient, the GChart does not need to be actually rendered within the browser for you to use this method.

Tip: If you need to access this mapping before the first real update, you can explicitly specify the min and max of this axis via setAxisMin and setAxisMax, and then call update before adding any curves to the chart (which, since the chart is empty, should be very fast). This approach will allow you to convert between model and pixel coordinates before the first real update, and before the chart is rendered in the browser.

Parameters:

pixelCoordinate - the distance, in pixels, from the left edge (for the x axis) or top edge (for the y or y2 axis) of the decorated chart to a point on this axis.

Returns:

that same position on this axis expressed in the the model units associated with this axis.

See Also:

getMouseCoordinate, clientToModel, modelToClient, modelToPixel, plotAreaPixelToModel

plotAreaPixelToModel

public abstract double plotAreaPixelToModel(int pixelCoordinate)

Converts a coordinate position in GChart's plot area pixel coordinates into the model units associated with this axis.

GChart's plot area pixel coordinates have their origin at the upper left corner of the plot area, and x pixel-coordinates that increase as you move right, and y pixel-coordinates that increase as you move down.

The plot area is the rectangular region bounded by the chart's axes, and with a size specified via setChartSize, where the chart's curves are typically displayed.

Apart from a shift in the origin of the pixel coordinates used, this method works just like pixelToModel; see that method for additional details, tips, and restrictions.

Parameters:

pixelCoordinate - the distance, in pixels, from the left edge (for the x axis) or top edge (for the y or y2 axis) of the plot area to a point on this axis.

Returns:

that same position on this axis expressed in the the model units associated with this axis.

See Also:

modelToPlotAreaPixel, pixelToModel, setChartSize

setAxisLabel

public void setAxisLabel(com.google.gwt.user.client.ui.Widget axisLabel)

Specifies the label of this axis.

This label will be positioned just outside of, and centered lengthwise on, the region adjacent to this axis that GChart reserves for this axis' tick labels.

Parameters:

axisLabel - a Widget to use as the label of this axis.

See Also:

getAxisLabel, setTickLabelThickness, setAxisLabelThickness

setAxisLabel

public void setAxisLabel(java.lang.String html)

Convenience method equivalent to setAxisLabel(new HTML(html))

Parameters:

html - HTML text used to define the axis label

See Also:

setAxisLabel(Widget)

setAxisLabelThickness

public void setAxisLabelThickness(int thickness)

Sets the thickness of the axis-label-holding region adjacent to the region allocated for tick labels.

The axis label widget will be centered in this region. Choose a thickness large enough to hold the largest font size you want users to be able to zoom up to without the axis label spilling over into adjacent regions.

If the axis label thickness is GChart.NAI (the default), and the widget defining the axis label implements HasHTML (or HasText) then GChart uses a thickness based on the estimated number of non-tag characters in the first <br> or <li> delimited line for y-axis labels, and based on the estimated number of (<br> or <li> delimited) text lines for x-axis labels.

Note that if the axis label is null (its default setting) then no space is allocated for the axis label, regardless of this thickness setting.

Parameters:

thickness - the thickness of the axis-label-holding region, in pixels, or GChart.NAI to use GChart's character-based default thickness estimates.

See Also:

getAxisLabelThickness, setAxisLabel

setAxisMax

public void setAxisMax(double max)

Specifies the maximum value visible on this axis.

Aspects of the chart rendered beyond this maximum will be clipped if the chart's clipToPlotArea property is true.

If Double.NaN is specified, this maximum is auto-determined as described in getAxisMax.

Performance tip: Using auto-determined axis limits (via Double.NaN) forces GChart, at the next update, to re-render many chart elements whenever the min or max data value displayed on this axis changes. These (often expensive) re-renderings can be avoided by using explicitly specified axis limits whenever possible.

Parameters:

max - maximum value visible on this axis, in "model units" (arbitrary, application-specific, units) or Double.NaN (the default value) to use an auto-determined maximum.

See Also:

getAxisMax, getDataMin, getDataMax, setClipToPlotArea

setAxisMin

public void setAxisMin(double min)

Specifies the minimum value of this axis.

Aspects of the chart rendered at positions before this minimum value will be clipped if the chart's clipToPlotArea property is true.

If Double.NaN is specified, this minimum is auto-determined as described in getAxisMin.

Performance tip: Using auto-determined axis limits (via Double.NaN) forces GChart, at the next update, to re-render many chart elements whenever the min or max data value displayed on this axis changes. These (often expensive) re-renderings can be avoided by using explicitly specified axis limits whenever possible.

Parameters:

min - minimum value visible on this axis, in "model units" (arbitrary, application-specific, units), or Double.NaN (the default) to use an auto-determined minimum.

See Also:

getAxisMin, getDataMin, getDataMax

setAxisVisible

public void setAxisVisible(boolean axisVisible)

Defines if this axis is visible. Note that this property only defines the visibility of the axis line itself, it does not control the visibility of tick marks or tick labels associated with the axis.

Tip:Tick marks can be made invisible by using setTickThickness to set the tick thickness to 0. Tick labels can be made invisible by using setTickLabelFontColor to set the tick label color to the chart's background color.

Parameters:

axisVisible - false to hide axis, true to show it.

See Also:

setTickThickness, setTickLabelFontColor, getAxisVisible

setHasGridlines

public void setHasGridlines(boolean hasGridlines)

Specifies if this axis should have gridlines. When an axis has gridlines, tick marks with indexes 0, N, 2*N,... where N is the value of this axis' ticksPerGridline property, are in effect extended across the entire chart.

Parameters:

hasGridlines - true to display gridlines, false (the default) to not display them.

See Also:

getHasGridlines, setTicksPerGridline

setTickCount

public void setTickCount(int tickCount)

Sets the number of ticks to be placed on this axis. The default tick count is 10. Ticks are always evenly spaced across the entire axis, unless explicitly specified via addTick.

Note that setting the tick count overrides (erases) any ticks explicitly specified via addTick.

Parameters:

tickCount - the number of ticks for this axis.

See Also:

getTickCount, addTick(double), addTick(double, String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int), setTickLabelFormat, setTickLabelFontSize, setTickLabelFontStyle, setTickLabelFontColor, setTickLabelFontWeight

setTickLabelFontWeight

public void setTickLabelFontWeight(java.lang.String cssWeight)

Specifies the weight of the font used in this axis' tick labels.

Parameters:

cssWeight - the weight of the font, such as bold, normal, light, 100, 200, ... 900, for tick labels.

See Also:

getTickLabelFontWeight, setTickLabelFormat, setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int), setTickLabelFontStyle, setTickLabelFontColor, setTickLabelFontSize, DEFAULT_TICK_LABEL_FONT_WEIGHT

setTickLabelFontColor

public void setTickLabelFontColor(java.lang.String cssColor)

Specifies the color of the font used to render tick labels for this axis.

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

Parameters:

cssColor - color of the font used to display this axis' tick labels, in standard CSS format.

See Also:

getTickLabelFontColor, setTickLabelFormat, setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int), setTickLabelFontStyle, setTickLabelFontWeight, setTickLabelFontSize

setTickLabelFontStyle

public void setTickLabelFontStyle(java.lang.String cssStyle)

Specifies the CSS font-style of this axis' tick labels.

Parameters:

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

See Also:

getTickLabelFontStyle, setTickLabelFormat, setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int), setTickLabelFontColor, setTickLabelFontWeight, setTickLabelFontSize, DEFAULT_TICK_LABEL_FONT_STYLE

setTickLabelFontSize

public void setTickLabelFontSize(int tickLabelFontSize)

Sets the CSS font size for tick labels on this axis, in pixels.

Parameters:

tickLabelFontSize - the font size of tick labels displayed on this axis.

See Also:

getTickLabelFontSize, setTickLabelFormat, setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int), setTickLabelFontStyle, setTickLabelFontColor, setTickLabelFontWeight, DEFAULT_TICK_LABEL_FONTSIZE

setTickLabelFormat

public void setTickLabelFormat(java.lang.String format)

Specifies a format string to be used in converting the numeric values associated with each tick on this axis into tick labels. This string must follow the conventions of the number format patterns used by the GWT NumberFormat class, with three exceptions:

1. Log10 inverse prefix: If the string begins with the prefix =10^ the value is replaced with pow(10.,value) and the so-transformed value is then formatted using the part of the format string that comes after this prefix, which must be a valid GWT NumberFormat pattern (e.g. "##.##").

   For an example of how to use this prefix to create a semi-log plot, see the Chart Gallery's GChartExample04.

2. Log2 inverse prefix: If the string begins with the prefix =2^ the value is replaced with pow(2.,value) and the so-transformed value is then formatted using the part of the format string that comes after this prefix, which must be a valid GWT NumberFormat pattern.

3. Date casting prefix: If the string begins with the prefix =(Date) the value is replaced with new Date((long) value) and the so-transformed value is then formatted using the format string that comes after this prefix, which must be a valid GWT DateTimeFormat pattern (e.g. "yyyy-MM-dd HH:mm"). For the special case format string of "=(Date)" (just the date casting prefix) GChart uses the DateTimeFormat returned by the DateTimeFormat.getShortDateTimeFormat method.

   Note that the values associated with this Axis must represent the number of milliseconds since January 1, 1970 (in the GMT time zone) whenever this date casting prefix is used.

   For example, if the x-axis tick label format were "=(Date)MMM-dd-yyyy HH", then, for a tick located at the x position of 0, the tick label would be "Jan-01-1970 00" (on a client in the GMT time zone) and for a tick located at the x position of 25*60*60*1000 (one day + one hour, in milliseconds) the tick label would be "Jan-02-1970 01" (again, on a GMT-based client). Results would be shifted appropriately on clients in different time zones.

   Note that if your chart is based on absolute, GMT-based, millisecond times then date labels will change when your chart is displayed on clients in different time zones. Sometimes, this is what you want. To keep the date labels the same in all time zones, convert date labels into Java Date objects in your client-side code, then use the Date.getTime method, also in your client-side code, to convert those dates into the millisecond values GChart requires. The Chart Gallery's GChartExample12 illustrates how to use this second approach to produce a time series chart whose date-time labels are the same in all time zones.

   Ben Martin describes an alternative (and more flexible) approach to formatting time series tick labels in his GChart tutorial. Ben's article, along with Malcolm Gorman's related GWT forum post were the origin of this date casting prefix. Thanks!

Though HTML text is not supported in the tick label format string, you can change the size, weight, style, and color of tick label text via the setTickLabelFont* family of methods. You can use HTML in tick labels (e.g. for a multi-line x-axis label) but but only if you define each tick label explicitly using the addTick method.

Parameters:

format - an appropriately prefixed GWT NumberFormat compatible or GWT DateTimeFormat compatible format string that defines how to convert tick values into tick labels.

See Also:

setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int), setTickLabelFontSize, setTickLabelFontStyle, setTickLabelFontColor, setTickLabelFontWeight, getTickLabelFormat

setTickLabelPadding

public void setTickLabelPadding(int tickLabelPadding)

Specifies the number of pixels of padding (blank space) between the tick marks and their labels.

With the default of 0, each tick label is flush against its tick mark.

Parameters:

tickLabelPadding - the amount of padding between tick labels and tick marks, in pixels.

See Also:

getTickLabelPadding, setTickLength, setTickLocation

setTickLabelThickness

public void setTickLabelThickness(int tickLabelThickness)

Specifies the thickness of the region adjacent to this axis that GChart will reserve for purposes of holding this axis' tick labels.

For vertical axes, this represents the width of the widest tick label, for horizontal axes, this represents the height of highest tick label.

By default, this property has the special "undefined" value GChart.NAI. With this value, the companion method getTickLabelThickness uses an HTML-based heuristic to estimate the thickness.

See Also:

getTickLabelThickness, setTickLabelFontSize, setTickLocation, setTickLabelPadding, setAxisLabel, NAI

setTicksPerGridline

public void setTicksPerGridline(int ticksPerGridline)

Specifies the ratio of the number of tick marks on the axis, to the number of gridlines on the axis.

For example, with the default value of 1, every tick has an associated gridline, whereas with a ticksPerGridline setting of 2, only the first, third, fifth, etc. ticks have gridlines.

This setting only has an impact when the axis' gridlines are turned on, that is, when this axis' getHasGridlines method returns true.

Parameters:

ticksPerGridline - the number of ticks on this axis per "gridline-extended" tick.

See Also:

setHasGridlines, setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int)

setTicksPerLabel

public void setTicksPerLabel(int ticksPerLabel)

Specifies the ratio of the number of tick marks on the axis, to the number of labeled tick marks on the axis.

For example, with the default value of 1, every tick is labeled, whereas with a ticksPerLabel setting of 2, only the first, third, fifth, etc. ticks are labeled.

This setting is only used when tick labels are specified implicitly via setTickCount. It is ignored when tick positions and their labels are explicitly specified via addTick.

Parameters:

ticksPerLabel - the ratio of the number of ticks, to the number of labeled ticks.

See Also:

setTickCount, addTick(double), addTick(double,String), addTick(double,String,int,int), addTick(double,Widget), addTick(double,Widget,int,int)

setTickLength

public abstract void setTickLength(int tickLength)

Sets this axis' tick length. Set the tick length to zero to eliminate the tick entirely.

Parameters:

tickLength - the length of the tick.

See Also:

getTickLength, setTickThickness, setTickLabelPadding, setTickLocation

setTickLocation

public void setTickLocation(GChart.TickLocation tickLocation)

Specifies the location of the tick marks relative to this axis, namely, if tick marks are outside, inside, or centered on this axis.

Parameters:

tickLocation - Specify either TickLocation.INSIDE, TickLocation.OUTSIDE, or TickLocation.CENTERED

See Also:

getTickLocation, setTickThickness, setTickLength, setTickLabelPadding

setTickThickness

public abstract void setTickThickness(int tickThickness)

Sets this axis' tick thickness.

Parameters:

tickThickness - the thickness of the tick.

See Also:

getTickThickness, setTickLength, setTickLabelPadding, setTickLocation