# Interface PlotSurface

All Known Implementing Classes:
  `GraphSurface, PtPlotSurface`

public interface PlotSurface
Defines a surface onto which plots are made. This surface will typically deal with drawing axes and labels and so on.

Two coordinate spaces are important when dealing with a PlotSurface: graphics space is referenced in integer coordinates and refers to the coordinates you deal with when you have a `Graphics` object, and data space is referenced in double coordinates and is the space in which the data points live. PlotSurface defines how to do the necessary conversions between them.

Since:
  16 Jun 2004
Author:
  Mark Taylor (Starlink)

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`MAX_COORD`
Gives the maximum absolute value which should be generated by any of the methods of this class as graphics coordinates.

## Method Summary

Modifier and Type
Method
Description
`Point`
`dataToGraphics(double x, double y, boolean insideOnly)`
Converts a point in data space to graphics space.
`Shape`
`getClip()`
Returns the clip region in which points may be plotted.
`JComponent`
`getComponent()`
Returns the graphical component on which the plotting surface is displayed.
`double[]`
`graphicsToData(int px, int py, boolean insideOnly)`
Converts a point in graphics space to data space.
`void`
`paintSurface(Graphics g)`
Paints the plotting surface.
`void`
`setDataRange(double xlo, double ylo, double xhi, double yhi)`
Requests a range of data space values to be visible on this plotting surface.
`void`
`setState(PlotState state)`
Signals to the plot the characteristics of the plot which will be performed.

## Field Details

### MAX_COORD

static final int MAX_COORD
Gives the maximum absolute value which should be generated by any of the methods of this class as graphics coordinates. This number is large, but smaller than `Integer.MAX_VALUE`. Any graphics coordinate comparable with `Integer.MAX_VALUE` will be far off the screen, so its exact value is unlikely to matter. The main purpose of mandating this limit is so that generated coordinates can be manipulated without much fear of arithmetic overflow.

If the limit were set fairly low (a few thousand?) this could also have the effect of preventing painting commands from attempting to draw lines a kilometre long, which can have an adverse effect on the graphics system. It could also lead to some graphical distortions.

See Also:
  - Constant Field Values

## Method Details

### dataToGraphics

Point dataToGraphics(double x, double y, boolean insideOnly)
Converts a point in data space to graphics space. If the `insideOnly` flag is true, then `null` will be returned in place of any result which would give a point lying outside the visible plotting area.

The coordinates of the returned point must have absolute values no greater than `MAX_COORD`.

Parameters:
  `x` - data space X coordinate
  `y` - data space Y coordinate
  `insideOnly` - true to restrict non-null results to those within the plotting surface
Returns:
  point in graphics space corresponding to (x,y), or `null`

### graphicsToData

double[] graphicsToData(int px, int py, boolean insideOnly)
Converts a point in graphics space to data space. If the `insideOnly` flag is true, then `null` will be returned in place of any result which would give a point lying outside the visible plotting area.

Parameters:
  `px` - graphics space X coordinate
  `py` - graphics space Y coordinate
  `insideOnly` - true to restrict non-null results to those within the plotting surface
Returns:
  a 2-element array giving x and y data space coordinates, or `null`

### getClip

Shape getClip()
Returns the clip region in which points may be plotted. The returned shape should be the sort which can be passed to `Graphics.setClip(java.awt.Shape)` - i.e. probably a `Rectangle`.

Returns:
  clip region representing data zone

### setState

void setState(PlotState state)
Signals to the plot the characteristics of the plot which will be performed. Setting this has no immediate effect, but when the component supplied by `getComponent()` next paints itself it should do so following the specifications made here.

Parameters:
  `state` - plot characteristics

### setDataRange

void setDataRange(double xlo, double ylo, double xhi, double yhi)
Requests a range of data space values to be visible on this plotting surface.

Parameters:
  `xlo` - (approximate) lower bound of X coordinate
  `ylo` - (approximate) lower bound of Y coordinate
  `xhi` - (approximate) upper bound of X coordinate
  `yhi` - (approximate) upper bound of Y coordinate

### getComponent

JComponent getComponent()
Returns the graphical component on which the plotting surface is displayed. This will contain things like axes, grids, labels etc. This component will normally override `JComponent.paintComponent(Graphics)` to give a plotting background in accordance with the most recently set `PlotState`.

Returns:
  plot surface display component

### paintSurface

void paintSurface(Graphics g)
Paints the plotting surface. This should do roughly the same as `getComponent.paintComponent`, except that it's public.

Requiring this here isn't very tidy, but following quite a bit of experimentation I can't work out any other way to do scatter plot image caching while still drawing to a potentially hardware-accelerated graphics context (see `ScatterPlot` implementation).

Parameters:
  `g` - graphics context