uk.ac.starlink.ttools.plot

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 and Description
static 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 and 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 Detail

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 Detail

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(java.awt.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