PlotPlacement (Starjava TTOOLS API)

java.lang.Object
- uk.ac.starlink.ttools.plot2.PlotPlacement

```
@Equality
public class PlotPlacement
extends java.lang.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

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`static <P,A> java.awt.Rectangle`	`calculateDataBounds(java.awt.Rectangle extBounds, Padding padding, SurfaceFactory<P,A> surfFact, P profile, A aspect, boolean withScroll, javax.swing.Icon legend, float[] legPos, java.lang.String title, ShadeAxis shadeAxis)`	Determines the bounds for the data part of a plot given its external dimensions and other information about it.
`static <P,A> java.awt.Insets`	`calculateDataInsets(java.awt.Rectangle extBounds, SurfaceFactory<P,A> surfFact, P profile, A aspect, boolean withScroll, javax.swing.Icon legend, float[] legPos, java.lang.String title, ShadeAxis shadeAxis, int pad)`	Determines the required insets for a plot to accommodate axis annotations etc.
`static <P,A> PlotPlacement`	`createPlacement(java.awt.Rectangle extBounds, Padding padding, SurfaceFactory<P,A> surfFact, P profile, A aspect, boolean withScroll, javax.swing.Icon legend, float[] legPos, java.lang.String title, ShadeAxis shadeAxis)`	Convenience method to create a plot placement given various inputs.
`static Decoration[]`	`createPlotDecorations(Surface surf, javax.swing.Icon legend, float[] legPos, java.lang.String title, ShadeAxis shadeAxis)`	Returns a list of plot decorations for things like the legend and shade colour ramp.
`javax.swing.Icon`	`createPlotIcon(javax.swing.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(java.lang.Object o)`
`java.awt.Rectangle`	`getBounds()`	Returns the external bounds of this placement.
`java.util.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

- Constructor Detail
  - PlotPlacement
```
public PlotPlacement(java.awt.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(java.awt.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 java.awt.Rectangle getBounds()
```
    Returns the external bounds of this placement.
    
    Returns:
    
    bounds
  - getSurface
```
public Surface getSurface()
```
    Returns the plot surface.
    
    Returns:
    
    surface
  - getDecorations
```
public java.util.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 javax.swing.Icon createPlotIcon(javax.swing.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(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - createPlacement
```
public static <P,A> PlotPlacement createPlacement(java.awt.Rectangle extBounds,
                                                  Padding padding,
                                                  SurfaceFactory<P,A> surfFact,
                                                  P profile,
                                                  A aspect,
                                                  boolean withScroll,
                                                  javax.swing.Icon legend,
                                                  float[] legPos,
                                                  java.lang.String title,
                                                  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
    
    legend - legend icon if required, or null
    
    legPos - legend position if intenal legend is required; 2-element (x,y) array, each element in range 0-1
    
    title - title text, or null
    
    shadeAxis - shader axis if required, or null
    
    Returns:
    
    new plot placement
  - calculateDataInsets
```
public static <P,A> java.awt.Insets calculateDataInsets(java.awt.Rectangle extBounds,
                                                        SurfaceFactory<P,A> surfFact,
                                                        P profile,
                                                        A aspect,
                                                        boolean withScroll,
                                                        javax.swing.Icon legend,
                                                        float[] legPos,
                                                        java.lang.String title,
                                                        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
    
    legend - legend icon if required, or null
    
    legPos - legend position if intenal legend is required; 2-element (x,y) array, each element in range 0-1
    
    title - title text, 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> java.awt.Rectangle calculateDataBounds(java.awt.Rectangle extBounds,
                                                           Padding padding,
                                                           SurfaceFactory<P,A> surfFact,
                                                           P profile,
                                                           A aspect,
                                                           boolean withScroll,
                                                           javax.swing.Icon legend,
                                                           float[] legPos,
                                                           java.lang.String title,
                                                           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
    
    legend - legend icon if required, or null
    
    legPos - legend position if intenal legend is required; 2-element (x,y) array, each element in range 0-1
    
    title - title text, or null
    
    shadeAxis - shader axis if required, or null
    
    Returns:
    
    data bounds rectangle
  - createPlotDecorations
```
public static Decoration[] createPlotDecorations(Surface surf,
                                                 javax.swing.Icon legend,
                                                 float[] legPos,
                                                 java.lang.String title,
                                                 ShadeAxis shadeAxis)
```
    Returns a list of plot decorations for things like the legend and shade colour ramp.
    
    Parameters:
    
    surf - plot surface
    
    legend - legend icon if required, or null
    
    legPos - legend position if intenal legend is required; 2-element (x,y) array, each element in range 0-1
    
    title - title text, or null
    
    shadeAxis - shader axis if required, or null
    
    Returns:
    
    list of decorations (may have zero elements)

Class PlotPlacement

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PlotPlacement

PlotPlacement

Method Detail

getBounds

getSurface

getDecorations

createPlotIcon

equals

hashCode

createPlacement

calculateDataInsets

calculateDataBounds

createPlotDecorations