Package uk.ac.starlink.topcat.plot2

## Class AxisController<P,A>

- java.lang.Object
- - uk.ac.starlink.topcat.plot2.AxisController<P,A>

- All Implemented Interfaces:
    `Configger`
  Direct Known Subclasses:
    `CartesianAxisController`, `SkyAxisController`

      public abstract class AxisController<P,A>
      extends java.lang.Object
      implements Configger

  Object which configures details of a plot's axes, including surface aspect and ranges. As well as methods which are used by the plot classes to interrogate and configure the plot programmatically, this supplies one or more controls to be placed in the GUI allowing user control of these things.
  Since:
    22 Jan 2014
  Author:
    Mark Taylor

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AxisController​(uk.ac.starlink.ttools.plot2.SurfaceFactory<P,A> surfFact)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addActionListener​(java.awt.event.ActionListener listener)` | Adds a listener notified when any of the controls changes.
    `protected void` | `addAspectConfigTab​(java.lang.String label, uk.ac.starlink.ttools.plot2.config.Specifier<uk.ac.starlink.ttools.plot2.config.ConfigMap> aspectSpecifier)` | Adds a tab to the main control for specifying the aspect.
    `void` | `addControl​(ConfigControl control)` | Adds a control to the list of controls managed by this object.
    `protected void` | `addNavigatorTab()` | Adds a tab to the main control for selecting navigator options.
    `boolean` | `assertHasKeys​(uk.ac.starlink.ttools.plot2.config.ConfigKey[] requiredKeys)` | Utility method to assert that all of a given set of keys are actually being obtained by this controller.
    `void` | `clearAspect()` | Clears any settings in tabs added by the `addAspectConfigTab` method.
    `protected boolean` | `clearRange​(P oldProfile, P newProfile, uk.ac.starlink.ttools.plot2.PlotLayer[] oldLayers, uk.ac.starlink.ttools.plot2.PlotLayer[] newLayers, boolean lock)` | Indicates whether a new configuration should result in clearing the current ranges and plot aspect.
    `abstract void` | `configureForLayers​(LayerControl[] layerControls)` | This abstract method provides a hook for implementations to adjust their GUI state based on the layer controls which will be supplying layers for them to plot.
    `protected uk.ac.starlink.topcat.plot2.AxisController.DataId` | `createDataId​(uk.ac.starlink.ttools.plot2.PlotLayer layer)` | Returns an object that characterises a plot layer for ranging purposes.
    `protected abstract boolean` | `forceClearRange​(P oldProfile, P newProfile)` | Determines whether the change between two profiles forces an unconditional re-range of the plotting surface.
    `java.awt.event.ActionListener` | `getActionForwarder()` | Returns an object which will forward actions to listeners registered with this panel.
    `A` | `getAspect()` | Returns the plot aspect to use for setting up the plot surface.
    `uk.ac.starlink.ttools.plot2.config.ConfigMap` | `getConfig()` | Returns the configuration defined by all this object's controls.
    `Control[]` | `getControls()` | Returns all the controls for user configuration of this controller.
    `ConfigControl` | `getMainControl()` | Returns the control that provides the main part of the GUI configurability.
    `uk.ac.starlink.ttools.plot2.Navigator<A>` | `getNavigator()` | Returns the navigator specified by this control.
    `uk.ac.starlink.ttools.plot.Range[]` | `getRanges()` | Returns the current fixed data coordinate ranges.
    `uk.ac.starlink.ttools.plot2.SurfaceFactory<P,A>` | `getSurfaceFactory()` | Returns this control's surface factory.
    `void` | `removeActionListener​(java.awt.event.ActionListener listener)` | Removes a listener previously added by addActionListener.
    `void` | `setAspect​(A aspect)` | Sets the plot aspect which defines the view on the data.
    `void` | `setRanges​(uk.ac.starlink.ttools.plot.Range[] ranges)` | Sets fixed data position coordinate ranges.
    `void` | `submitReports​(java.util.Map<LayerId,uk.ac.starlink.ttools.plot2.ReportMap> reports)` | Accepts report information generated by plotting layers.
    `void` | `updateState​(P profile, uk.ac.starlink.ttools.plot2.PlotLayer[] layers, boolean axisLock)` | Configures this controller for a given set of plot layers.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### AxisController

          protected AxisController​(uk.ac.starlink.ttools.plot2.SurfaceFactory<P,A> surfFact)

      Constructor. The surface factory is supplied. This is not actually required by the AxisControl class, but most subclasses will need it so it's convenient to store it here.
      Parameters:
        `surfFact` - plot surface factory

  - ### Method Detail

    - #### getSurfaceFactory

          public uk.ac.starlink.ttools.plot2.SurfaceFactory<P,A> getSurfaceFactory()

      Returns this control's surface factory.
      Returns:
        plot surface factory

    - #### getMainControl

          public ConfigControl getMainControl()

      Returns the control that provides the main part of the GUI configurability. Subclasses may provide additional controls.
      Returns:
        main control

    - #### getControls

          public Control[] getControls()

      Returns all the controls for user configuration of this controller. This includes the main control and possibly others.
      Returns:
        user controls

    - #### addControl

          public void addControl​(ConfigControl control)

      Adds a control to the list of controls managed by this object.
      Parameters:
        `control` - control to add

    - #### getConfig

          public uk.ac.starlink.ttools.plot2.config.ConfigMap getConfig()

      Returns the configuration defined by all this object's controls.
      Specified by:
        `getConfig` in interface `Configger`
      Returns:
        config map

    - #### addActionListener

          public void addActionListener​(java.awt.event.ActionListener listener)

      Adds a listener notified when any of the controls changes.
      Parameters:
        `listener` - listener to add

    - #### removeActionListener

          public void removeActionListener​(java.awt.event.ActionListener listener)

      Removes a listener previously added by addActionListener.
      Parameters:
        `listener` - listener to remove

    - #### getActionForwarder

          public java.awt.event.ActionListener getActionForwarder()

      Returns an object which will forward actions to listeners registered with this panel.
      Returns:
        action forwarder

    - #### setRanges

          public void setRanges​(uk.ac.starlink.ttools.plot.Range[] ranges)

      Sets fixed data position coordinate ranges. If these are not set then they may need to be calculated by examining the data to work out the plot aspect. Setting them to null ensures a re-range if required next time.
      Parameters:
        `ranges` - fixed data position coordinate ranges, or null to clear

    - #### getRanges

          public uk.ac.starlink.ttools.plot.Range[] getRanges()

      Returns the current fixed data coordinate ranges. If not known, null is returned.
      Returns:
        fixed data position coordinate ranges, or null if not known

    - #### setAspect

          public void setAspect​(A aspect)

      Sets the plot aspect which defines the view on the data. If not set, it may have to be worked out from config and range inputs.
      Parameters:
        `aspect` - fixed aspect, or null to clear

    - #### getAspect

          public A getAspect()

      Returns the plot aspect to use for setting up the plot surface. If not known, null is returned.
      Returns:
        fixed aspect, or null if none set

    - #### configureForLayers

          public abstract void configureForLayers​(LayerControl[] layerControls)

      This abstract method provides a hook for implementations to adjust their GUI state based on the layer controls which will be supplying layers for them to plot.
      Parameters:
        `layerControls` - layer controls expected to provide layers to be plotted on these axes

    - #### addNavigatorTab

          protected void addNavigatorTab()

      Adds a tab to the main control for selecting navigator options. These are determined by the surface factory.

    - #### getNavigator

          public uk.ac.starlink.ttools.plot2.Navigator<A> getNavigator()

      Returns the navigator specified by this control.
      Returns:
        current navigator

    - #### addAspectConfigTab

          protected void addAspectConfigTab​(java.lang.String label,
                                            uk.ac.starlink.ttools.plot2.config.Specifier<uk.ac.starlink.ttools.plot2.config.ConfigMap> aspectSpecifier)

      Adds a tab to the main control for specifying the aspect. This is like a config tab for the aspect keys, but has additional submit decoration.
      Parameters:
        `label` - tab label
        `aspectSpecifier` - config specifier for aspect keys

    - #### clearAspect

          public void clearAspect()

      Clears any settings in tabs added by the `addAspectConfigTab` method.

    - #### updateState

          public void updateState​(P profile,
                                  uk.ac.starlink.ttools.plot2.PlotLayer[] layers,
                                  boolean axisLock)

      Configures this controller for a given set of plot layers. This may trigger a resetting of the aspect and ranges, generally if the new plot is sufficiently different from most recent one. Whether that's the case is determined by calling `clearRange`.

      This isn't perfect, since it only allows to clear the range or not. Sometimes you might want finer control, e.g. to clear the range in one dimension and retain it in others. It may be possible to fit that into the updateState API, but it would require more work.

      Parameters:
        `profile` - surface profile
        `layers` - layers which will be plotted
        `axisLock` - whether re-ranging is inhibited; normally, if true axes will not be reset by this method, but the implementation can override that if it needs to

    - #### assertHasKeys

          public boolean assertHasKeys​(uk.ac.starlink.ttools.plot2.config.ConfigKey[] requiredKeys)

      Utility method to assert that all of a given set of keys are actually being obtained by this controller.
      Parameters:
        `requiredKeys` - list of keys this control should obtain
      Returns:
        true iff the `getConfig` method contains entries for all the required keys
      Throws:
        `java.lang.AssertionError` - if the result would be false and assertions are enabled

    - #### submitReports

          public void submitReports​(java.util.Map<LayerId,uk.ac.starlink.ttools.plot2.ReportMap> reports)

      Accepts report information generated by plotting layers. Null map values are permitted, with the same meaning as an empty map.

      The default implementation does nothing, but subclasses may override it to enquire about plot results.

      Parameters:
        `reports` - per-layer plot reports for layers generated by the most recent plot

    - #### clearRange

          protected boolean clearRange​(P oldProfile,
                                       P newProfile,
                                       uk.ac.starlink.ttools.plot2.PlotLayer[] oldLayers,
                                       uk.ac.starlink.ttools.plot2.PlotLayer[] newLayers,
                                       boolean lock)

      Indicates whether a new configuration should result in clearing the current ranges and plot aspect.
      Parameters:
        `oldProfile` - profile for last plot
        `newProfile` - profile for next plot
        `oldLayers` - layer set for last plot
        `newLayers` - layer set for next plot
        `lock` - whether re-ranging is inhibited; normally, if `lock` is true this method should return false, but the implementation can overrule this and return true even when locked if it needs to
      Returns:
        true iff the range should be re-established for the next plot

    - #### forceClearRange

          protected abstract boolean forceClearRange​(P oldProfile,
                                                     P newProfile)

      Determines whether the change between two profiles forces an unconditional re-range of the plotting surface. This method should return true if the plotting surface will change between the old and new supplied profiles sufficiently to invalidate previously calculated auto range data.
      Parameters:
        `oldProfile` - profile before change
        `newProfile` - profile after change
      Returns:
        true if a new auto-ranging is required

    - #### createDataId

          @Equality
          protected uk.ac.starlink.topcat.plot2.AxisController.DataId createDataId​(uk.ac.starlink.ttools.plot2.PlotLayer layer)

      Returns an object that characterises a plot layer for ranging purposes. Two layers that return the equivalent (`Equality`) results from this method should be treated as having the same ranges.
      Parameters:
        `layer` - plot layer
      Returns:
        opaque object characterising identity of ranging information associated with the layer, or null if no range

Copyright © 2003-2018 CCLRC: Council for the Central Laboratory of the Research Councils. All Rights Reserved.