com.googlecode.gchart.client
Class GChart.YAxis

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

Enclosing class:

GChart

public class GChart.YAxis
extends GChart.Axis

The left y-axis of a GChart.

See Also:

getYAxis

Method Summary

double	clientToModel(int clientCoordinate) Converts a pixel, client-window coordinate position along this axis into the model units associated with this axis.
double	getDataMax() Returns the maximum data value associated with values represented on this axis.
double	getDataMin() Returns the minimum data value associated with values represented on this axis.
double	getMouseCoordinate() Returns the coordinate along this axis that is associated with the last "GChart-tracked" mouse location.
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.
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.
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.
double	pixelToModel(int pixelCoordinate) Converts a coordinate position in GChart's decorated chart pixel coordinates into the model units associated with this axis.
double	plotAreaPixelToModel(int pixelCoordinate) Converts a coordinate position in GChart's plot area pixel coordinates into the model units associated with this axis.
void	setTickLength(int tickLength) Sets this axis' tick length.
void	setTickThickness(int tickThickness) Sets this axis' tick thickness.

Methods inherited from class com.googlecode.gchart.client.GChart.Axis

addTick, addTick, addTick, addTick, addTick, clearTicks, formatAsTickLabel, formatNumberAsTickLabel, getAxisLabel, getAxisLabelThickness, getAxisMax, getAxisMin, getAxisVisible, getHasGridlines, getNCurvesVisibleOnAxis, getTickCount, getTickLabelFontColor, getTickLabelFontSize, getTickLabelFontStyle, getTickLabelFontWeight, getTickLabelFormat, getTickLabelPadding, getTickLabelThickness, getTickLength, getTickLocation, getTickSpace, getTicksPerGridline, getTicksPerLabel, getTickThickness, setAxisLabel, setAxisLabel, setAxisLabelThickness, setAxisMax, setAxisMin, setAxisVisible, setHasGridlines, setTickCount, setTickLabelFontColor, setTickLabelFontSize, setTickLabelFontStyle, setTickLabelFontWeight, setTickLabelFormat, setTickLabelPadding, setTickLabelThickness, setTickLocation, setTicksPerGridline, setTicksPerLabel

Methods inherited from class java.lang.Object

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

Method Detail

clientToModel

public double clientToModel(int clientCoordinate)

Description copied from class: GChart.Axis

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.

Specified by:

clientToModel in class GChart.Axis

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

getDataMax

public double getDataMax()

Description copied from class: GChart.Axis

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.

Specified by:

getDataMax in class GChart.Axis

Returns:

the maximum value associated with values mapped onto this axis.

See Also:

getDataMin, getAxisMax, getAxisMin

getDataMin

public double getDataMin()

Description copied from class: GChart.Axis

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.

Specified by:

getDataMin in class GChart.Axis

Returns:

the minimum value associated with values mapped onto this axis.

See Also:

getDataMax, getAxisMax, getAxisMax

getMouseCoordinate

public double getMouseCoordinate()

Description copied from class: GChart.Axis

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.

Specified by:

getMouseCoordinate in class GChart.Axis

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

modelToClient

public double modelToClient(double modelCoordinate)

Description copied from class: GChart.Axis

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.

Specified by:

modelToClient in class GChart.Axis

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 double modelToPixel(double modelCoordinate)

Description copied from class: GChart.Axis

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.

Specified by:

modelToPixel in class GChart.Axis

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 double modelToPlotAreaPixel(double modelCoordinate)

Description copied from class: GChart.Axis

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.

Specified by:

modelToPlotAreaPixel in class GChart.Axis

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 double pixelToModel(int pixelCoordinate)

Description copied from class: GChart.Axis

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.

Specified by:

pixelToModel in class GChart.Axis

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 double plotAreaPixelToModel(int pixelCoordinate)

Description copied from class: GChart.Axis

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.

Specified by:

plotAreaPixelToModel in class GChart.Axis

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

setTickLength

public void setTickLength(int tickLength)

Description copied from class: GChart.Axis

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

Specified by:

setTickLength in class GChart.Axis

Parameters:

tickLength - the length of the tick.

See Also:

getTickLength, setTickThickness, setTickLabelPadding, setTickLocation

setTickThickness

public void setTickThickness(int tickThickness)

Description copied from class: GChart.Axis

Sets this axis' tick thickness.

Specified by:

setTickThickness in class GChart.Axis

Parameters:

tickThickness - the thickness of the tick.

See Also:

getTickThickness, setTickLength, setTickLabelPadding, setTickLocation