PlotStateFactory (Starjava TTOOLS API)

java.lang.Object
- uk.ac.starlink.ttools.plottask.PlotStateFactory

Direct Known Subclasses:

HistogramPlotStateFactory, Plot3DStateFactory
```
public class PlotStateFactory
extends java.lang.Object
```
Obtains a PlotState and associated PlotData from the execution environment. It sets up and interrogates a lot of parameters which describe how the plot should be done, and organises this information into a single object, a PlotState. It is subclassed for different plot types.

Since:

22 Apr 2008

Author:

Mark Taylor

Field Summary

Fields
Modifier and Type	Field	Description
`static java.lang.String`	`AUX_VARIABLE`	Symbolic suffix representing an auxiliary axis in per-aux parameter names.
`static java.lang.String`	`SUBSET_VARIABLE`	Symbolic suffix representing a subset in per-subset parameter names.
`static java.lang.String`	`TABLE_VARIABLE`	Symbolic suffix representing a table in per-table parameter names.

Constructor Summary

Constructors
Constructor	Description
`PlotStateFactory(java.lang.String[] dimNames, boolean useAux, boolean useLabel, int errNdim)`	Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`Style`	`adjustFromData(Style style, int iset, DataBounds bounds)`	Updates a plotting style generated by this factory with information generated from a first pass through the data.
`DataBounds`	`calculateBounds(PlotState state, TablePlot plot)`	Calculates data bounds for a given data set as appropriate for the given plot.
`protected void`	`configureFromBounds(PlotState state, DataBounds bounds)`	Updates a plot state generated by this factory with information generated from a first pass through the data.
`void`	`configureFromData(PlotState state, TablePlot plot)`	Performs additional plot state configuration which may require a pass through the data.
`protected void`	`configurePlotState(PlotState state, uk.ac.starlink.task.Environment env)`	Configures a PlotState object by examining parameter values in a given execution environment.
`protected TablePlotData`	`createPlotData(uk.ac.starlink.task.Environment env, java.lang.String tLabel, uk.ac.starlink.table.StarTable table, java.lang.String[] setExprs, java.lang.String[] setNames, Style[] setStyles, java.lang.String labelExpr, java.lang.String[] coordExprs, java.lang.String[] errExprs)`	Constructs a PlotData object.
`protected PlotState`	`createPlotState()`	Creates a new unconfigured PlotState object suitable for configuration by this factory.
`protected StyleFactory`	`createStyleFactory(java.lang.String prefix)`	Constructs a style factory which can retrieve a plotting style suitable for use with this factory from the environment.
`uk.ac.starlink.task.Parameter[]`	`getParameters()`	Returns the parameters associated with this object.
`PlotState`	`getPlotState(uk.ac.starlink.task.Environment env)`	Returns a configured PlotState obtained from parameter values specified by the given execution environment.
`boolean`	`requiresAdjustFromData(Style style)`	Indicates whether a given style generated by this factory needs to be updated with information from a first pass through the data.
`protected boolean`	`requiresConfigureFromBounds(PlotState state)`	Indicates whether it is necessary to calculate the DataBounds for a given PlotState before it is ready to be used.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - TABLE_VARIABLE
```
public static final java.lang.String TABLE_VARIABLE
```
    Symbolic suffix representing a table in per-table parameter names.
    
    See Also:
    
    Constant Field Values
  - SUBSET_VARIABLE
```
public static final java.lang.String SUBSET_VARIABLE
```
    Symbolic suffix representing a subset in per-subset parameter names.
    
    See Also:
    
    Constant Field Values
  - AUX_VARIABLE
```
public static final java.lang.String AUX_VARIABLE
```
    Symbolic suffix representing an auxiliary axis in per-aux parameter names. Currently blank, as only one auxiliary axis is provided for.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PlotStateFactory
```
public PlotStateFactory(java.lang.String[] dimNames,
                        boolean useAux,
                        boolean useLabel,
                        int errNdim)
```
    Constructor.
    
    Parameters:
    
    dimNames - names of main plot dimensions (typically "X", "Y", etc);
    
    useAux - whether auxiliary axes are used
    
    useLabel - whether point text labelling is used
    
    errNdim - number of axes for which errors can be plotted
- Method Detail
  - getParameters
```
public uk.ac.starlink.task.Parameter[] getParameters()
```
    Returns the parameters associated with this object. The returned list is intended for external use in documentation; the parameter objects returned may or may not be those used for obtaining values from a particular execution environment. For this reason they may have names which are symbolic, that is, represent possible parameter names. Since actual parameter names are dynamically determined from other parameter names, it is not possible to return an exhaustive list.
    
    Returns:
    
    array of parameters to be used for documentation
  - getPlotState
```
public PlotState getPlotState(uk.ac.starlink.task.Environment env)
                       throws uk.ac.starlink.task.TaskException
```
    Returns a configured PlotState obtained from parameter values specified by the given execution environment.
    
    Parameters:
    
    env - execution environment
    
    Throws:
    
    uk.ac.starlink.task.TaskException
  - createPlotState
```
protected PlotState createPlotState()
```
    Creates a new unconfigured PlotState object suitable for configuration by this factory.
    
    Returns:
    
    plot state
  - configurePlotState
```
protected void configurePlotState(PlotState state,
                                  uk.ac.starlink.task.Environment env)
                           throws uk.ac.starlink.task.TaskException
```
    Configures a PlotState object by examining parameter values in a given execution environment. Such an object was presumably previously created by a call to createPlotState().
    
    Parameters:
    
    state - plot state to configure
    
    env - execution environment
    
    Throws:
    
    uk.ac.starlink.task.TaskException
  - createPlotData
```
protected TablePlotData createPlotData(uk.ac.starlink.task.Environment env,
                                       java.lang.String tLabel,
                                       uk.ac.starlink.table.StarTable table,
                                       java.lang.String[] setExprs,
                                       java.lang.String[] setNames,
                                       Style[] setStyles,
                                       java.lang.String labelExpr,
                                       java.lang.String[] coordExprs,
                                       java.lang.String[] errExprs)
                                throws uk.ac.starlink.task.TaskException,
                                       gnu.jel.CompilationException
```
    Constructs a PlotData object. Called by configurePlotState(uk.ac.starlink.ttools.plot.PlotState, uk.ac.starlink.task.Environment); may be overridden by subclasses.
    
    Parameters:
    
    env - execution environment
    
    tLabel - table identifier suffix
    
    table - input table
    
    setExprs - nset-element JEL boolean-valued expression array for set inclusion
    
    setNames - nset-element set name array
    
    setStyles - nset-elemnt set style array
    
    labelExpr - JEL expression for text label
    
    coordExprs - ndim-element JEL double-valued expression array for coordinate values
    
    errExprs - nerr-element expression(s) array for error values
    
    Returns:
    
    new PlotData object based on parameters
    
    Throws:
    
    uk.ac.starlink.task.TaskException
    
    gnu.jel.CompilationException
  - configureFromData
```
public void configureFromData(PlotState state,
                              TablePlot plot)
                       throws uk.ac.starlink.task.TaskException,
                              java.io.IOException
```
    Performs additional plot state configuration which may require a pass through the data. This may do zero or more of the following:
    1. Configure the range attributes of the given state, ensuring that they have non-NaN values.
    Parameters:
    
    state - plot state whose ranges will to be configured
    
    plot - table plot for which configuration is to be done
    
    Throws:
    
    uk.ac.starlink.task.TaskException
    
    java.io.IOException
  - calculateBounds
```
public DataBounds calculateBounds(PlotState state,
                                  TablePlot plot)
```
    Calculates data bounds for a given data set as appropriate for the given plot.
    
    Parameters:
    
    state - plot state
    
    plot - plot object
  - requiresConfigureFromBounds
```
protected boolean requiresConfigureFromBounds(PlotState state)
```
    Indicates whether it is necessary to calculate the DataBounds for a given PlotState before it is ready to be used. Iff true is returned, then configureFromBounds(uk.ac.starlink.ttools.plot.PlotState, uk.ac.starlink.ttools.plot.DataBounds) will be called later.
    
    Parameters:
    
    state - plot state
    
    Returns:
    
    whether configureFromBounds should be called
  - configureFromBounds
```
protected void configureFromBounds(PlotState state,
                                   DataBounds bounds)
                            throws uk.ac.starlink.task.TaskException
```
    Updates a plot state generated by this factory with information generated from a first pass through the data.
    
    Parameters:
    
    state - plot state to update
    
    bounds - data bounds calculated by a pass through the data
    
    Throws:
    
    uk.ac.starlink.task.TaskException
  - requiresAdjustFromData
```
public boolean requiresAdjustFromData(Style style)
```
    Indicates whether a given style generated by this factory needs to be updated with information from a first pass through the data. Iff true is returned, then adjustFromData(uk.ac.starlink.ttools.plot.Style, int, uk.ac.starlink.ttools.plot.DataBounds) will be called later.
    
    Parameters:
    
    style - plot style to consider
    
    Returns:
    
    true iff adjustFromData should be called on style
  - adjustFromData
```
public Style adjustFromData(Style style,
                            int iset,
                            DataBounds bounds)
```
    Updates a plotting style generated by this factory with information generated from a first pass through the data.
    
    Parameters:
    
    style - plot style to update
    
    iset - set index for which style is used
    
    bounds - data bounds calculated by a pass through the data
  - createStyleFactory
```
protected StyleFactory createStyleFactory(java.lang.String prefix)
```
    Constructs a style factory which can retrieve a plotting style suitable for use with this factory from the environment.
    
    Parameters:
    
    prefix - prefix to use for all style-type variables

Class PlotStateFactory

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TABLE_VARIABLE

SUBSET_VARIABLE

AUX_VARIABLE

Constructor Detail

PlotStateFactory

Method Detail

getParameters

getPlotState

createPlotState

configurePlotState

createPlotData

configureFromData

calculateBounds

requiresConfigureFromBounds

configureFromBounds

requiresAdjustFromData

adjustFromData

createStyleFactory