uk.ac.starlink.ttools.plot2

Class PlotPlacement

java.lang.Object

uk.ac.starlink.ttools.plot2.PlotPlacement

@Equality
public class PlotPlacement
extends Object

Aggregates a Surface and the Rectangle that it is placed within. It may also store decorations to be painted on top of the plot. Class instances themselves may be compared for equality, but don't do much else. Several static methods however are provided to assist in creating instances, in particular doing the non-trivial work to determine how much external space is required for legends etc.

Note instances of this class are not immutable, since the decoration list may be changed.

Since:

12 Feb 2013

Author:

Mark Taylor

Field Summary

Fields

Modifier and Type	Field and Description
static int	PAD Default external padding in pixels to accommodate axis line width.

Constructor Summary

Constructors

Constructor and Description
PlotPlacement(Rectangle bounds, Surface surface) Constructs a placement with no decorations.
PlotPlacement(Rectangle bounds, Surface surface, Decoration[] decorations) Constructs a placement with an initial list of decorations.

Method Summary

Modifier and Type	Method and Description
static Surround	calculateApproxDecorationSurround(Rectangle extBounds, Trimming trimming, ShadeAxis shadeAxis, java.util.function.Supplier<Captioner> capFact) Calculates the space surrounding a plot required for trimming and shade axis.
static <P,A> Rectangle	calculateDataBounds(Rectangle extBounds, Padding padding, SurfaceFactory<P,A> surfFact, P profile, A aspect, boolean withScroll, Trimming trimming, ShadeAxis shadeAxis) Determines the bounds for the data part of a plot given its external dimensions and other information about it.
static <P,A> Insets	calculateDataInsets(Rectangle extBounds, SurfaceFactory<P,A> surfFact, P profile, A aspect, boolean withScroll, Trimming trimming, ShadeAxis shadeAxis, int pad) Determines the required insets for a plot to accommodate axis annotations etc.
static <P,A> PlotPlacement	createPlacement(Rectangle extBounds, Padding padding, SurfaceFactory<P,A> surfFact, P profile, A aspect, boolean withScroll, Trimming trimming, ShadeAxis shadeAxis) Convenience method to create a plot placement given various inputs.
static Decoration[]	createPlotDecorations(PlotFrame frame, Trimming trimming, ShadeAxis shadeAxis) Returns a list of plot decorations for things like the legend and shade colour ramp.
Icon	createPlotIcon(Icon dataIcon) Takes an icon containing plot background and layers, and turns it into one positioned in an external rectangle with surface foreground (axes) and other decorations.
boolean	equals(Object o)
Rectangle	getBounds() Returns the external bounds of this placement.
List<Decoration>	getDecorations() Returns a list of decorations to be painted over the finished plot.
Surface	getSurface() Returns the plot surface.
int	hashCode()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

PAD

public static final int PAD

Default external padding in pixels to accommodate axis line width.

See Also:

Constant Field Values

Constructor Detail

PlotPlacement

public PlotPlacement(Rectangle bounds,
                     Surface surface)

Constructs a placement with no decorations.

Parameters:

bounds - external bounds within which plot is to be placed

surface - plot surface

PlotPlacement

public PlotPlacement(Rectangle bounds,
                     Surface surface,
                     Decoration[] decorations)

Constructs a placement with an initial list of decorations.

Parameters:

bounds - external bounds within which plot is to be placed

surface - plot surface

decorations - initial list of decorations; note more can be added later

Method Detail

getBounds

public Rectangle getBounds()

Returns the external bounds of this placement.

Returns:

bounds

getSurface

public Surface getSurface()

Returns the plot surface.

Returns:

surface

getDecorations

public List<Decoration> getDecorations()

Returns a list of decorations to be painted over the finished plot. This list may be modified to add or remove decoration items.

Returns:

modifiable list of decoration objects

createPlotIcon

public Icon createPlotIcon(Icon dataIcon)

Takes an icon containing plot background and layers, and turns it into one positioned in an external rectangle with surface foreground (axes) and other decorations.

Parameters:

dataIcon - icon as generated by PaperType.createDataIcon(uk.ac.starlink.ttools.plot2.Surface, uk.ac.starlink.ttools.plot2.Drawing[], java.lang.Object[], uk.ac.starlink.ttools.plot2.data.DataStore, boolean)

Returns:

final plot icon to be drawn at the graphics origin

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

createPlacement

public static <P,A> PlotPlacement createPlacement(Rectangle extBounds,
                                                  Padding padding,
                                                  SurfaceFactory<P,A> surfFact,
                                                  P profile,
                                                  A aspect,
                                                  boolean withScroll,
                                                  Trimming trimming,
                                                  ShadeAxis shadeAxis)

Convenience method to create a plot placement given various inputs. In particular it works out how much space is required for decorations like axis annotations, legend etc.

Parameters:

extBounds - external bounds of plot placement

padding - requirements for outer padding, or null

surfFact - surface factory

profile - factory-specific surface profile

aspect - factory-specific surface aspect

withScroll - true if the placement should work well with future scrolling

trimming - specification for static decorations, or null

shadeAxis - shader axis if required, or null

Returns:

new plot placement

calculateApproxDecorationSurround

public static Surround calculateApproxDecorationSurround(Rectangle extBounds,
                                                         Trimming trimming,
                                                         ShadeAxis shadeAxis,
                                                         java.util.function.Supplier<Captioner> capFact)

Calculates the space surrounding a plot required for trimming and shade axis. These do not depend much on the size of the plot bounds.

Parameters:

extBounds - external bounds of plot placement

trimming - specification for static decorations, or null

shadeAxis - shader axis if required, or null

capFact - supplier for a Captioner; may return null if no title is required

Returns:

padding space required to accommodate decorations

calculateDataInsets

public static <P,A> Insets calculateDataInsets(Rectangle extBounds,
                                               SurfaceFactory<P,A> surfFact,
                                               P profile,
                                               A aspect,
                                               boolean withScroll,
                                               Trimming trimming,
                                               ShadeAxis shadeAxis,
                                               int pad)

Determines the required insets for a plot to accommodate axis annotations etc.

Parameters:

extBounds - external bounds of plot placement

surfFact - surface factory

profile - factory-specific surface profile

aspect - factory-specific surface aspect

withScroll - true if the placement should work well with future scrolling

trimming - specification for static decorations, or null

shadeAxis - shader axis if required, or null

pad - extra padding in pixels around the outside

Returns:

data bounds rectangle

calculateDataBounds

public static <P,A> Rectangle calculateDataBounds(Rectangle extBounds,
                                                  Padding padding,
                                                  SurfaceFactory<P,A> surfFact,
                                                  P profile,
                                                  A aspect,
                                                  boolean withScroll,
                                                  Trimming trimming,
                                                  ShadeAxis shadeAxis)

Determines the bounds for the data part of a plot given its external dimensions and other information about it. It does this by assessing how much space will be required for axis annotations etc.

Parameters:

extBounds - external bounds of plot placement

padding - preferences for outer padding, or null

surfFact - surface factory

profile - factory-specific surface profile

aspect - factory-specific surface aspect

withScroll - true if the placement should work well with future scrolling

trimming - specification for static decorations, or null

shadeAxis - shader axis if required, or null

Returns:

data bounds rectangle

createPlotDecorations

public static Decoration[] createPlotDecorations(PlotFrame frame,
                                                 Trimming trimming,
                                                 ShadeAxis shadeAxis)

Returns a list of plot decorations for things like the legend and shade colour ramp.

Parameters:

frame - geometry of area to be decorated

trimming - specification for static decorations, or null

shadeAxis - shader axis if required, or null

Returns:

list of decorations (may have zero elements)