com.orsoncharts.axis

## Class AbstractValueAxis3D

- java.lang.Object
- - com.orsoncharts.axis.AbstractAxis3D
  - - com.orsoncharts.axis.AbstractValueAxis3D

- All Implemented Interfaces:
    Axis3D, ValueAxis3D, ChartElement, MarkerChangeListener, java.io.Serializable, java.util.EventListener
  Direct Known Subclasses:
    LogAxis3D, NumberAxis3D

      public abstract class AbstractValueAxis3D
      extends AbstractAxis3D
      implements ValueAxis3D, java.io.Serializable

  A base class for implementing numerical axes.
  NOTE: This class is serializable, but the serialization format is subject to change in future releases and should not be relied upon for persisting instances of this class.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Range` | `range` The axis range.

    - ### Fields inherited from class com.orsoncharts.axis.AbstractAxis3D

      `DEFAULT_LABEL_COLOR, DEFAULT_LABEL_FONT, DEFAULT_LABEL_OFFSET, DEFAULT_LINE_COLOR, DEFAULT_LINE_STROKE, DEFAULT_TICK_LABEL_COLOR, DEFAULT_TICK_LABEL_FONT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractValueAxis3D(java.lang.String label, Range range)` Creates a new axis instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract Range` | `adjustedDataRange(Range range)` Adjusts the range by adding the lower and upper margins and taking into account any other settings.
    `protected java.lang.String` | `axisStr()` Returns a string representing the configured type of the axis.
    `void` | `configureAsValueAxis(CategoryPlot3D plot)` Configures the axis to be used as the value axis for the specified plot.
    `void` | `configureAsXAxis(XYZPlot plot)` Configures the axis to be used as the x-axis for the specified plot.
    `void` | `configureAsYAxis(XYZPlot plot)` Configures the axis to be used as the y-axis for the specified plot.
    `void` | `configureAsZAxis(XYZPlot plot)` Configures the axis to be used as the z-axis for the specified plot.
    `boolean` | `equals(java.lang.Object obj)` Tests this instance for equality with an arbitrary object.
    `java.util.List<MarkerData>` | `generateMarkerData()` Generates and returns a list of marker data items for the axis.
    `ValueAxis3DType` | `getConfiguredType()` Returns the configured type for the axis.
    `Range` | `getDefaultAutoRange()` Returns the default range used when the `autoAdjustRange` flag is `true` but the dataset contains no values.
    `double` | `getLowerMargin()` Returns the size of the lower margin that is added by the auto-range calculation, as a percentage of the data range.
    `ValueMarker` | `getMarker(java.lang.String key)` Returns the marker with the specified key, if there is one.
    `java.util.Map<java.lang.String,ValueMarker>` | `getMarkers()` Returns a new map containing the markers assigned to this axis.
    `double` | `getMinAutoRangeLength()` Returns the minimum length for the axis range when auto-calculated.
    `Range` | `getRange()` Returns the axis range.
    `double` | `getTickLabelFactor()` Returns the tick label factor, a multiplier for the label height to determine the maximum number of tick labels that can be displayed.
    `double` | `getTickLabelOffset()` Returns the tick label offset, the gap between the tick marks and the tick labels (in Java2D units).
    `LabelOrientation` | `getTickLabelOrientation()` Returns the orientation for the tick labels.
    `double` | `getTickMarkLength()` Returns the length of the tick marks (in Java2D units).
    `java.awt.Paint` | `getTickMarkPaint()` Returns the paint used to draw the tick marks.
    `java.awt.Stroke` | `getTickMarkStroke()` Returns the stroke used to draw the tick marks.
    `double` | `getUpperMargin()` Returns the size of the upper margin that is added by the auto-range calculation, as a percentage of the data range.
    `boolean` | `isAutoAdjustRange()` Returns the flag that controls whether or not the axis range is automatically updated in response to dataset changes.
    `boolean` | `isInverted()` Returns the flag that determines whether or not the order of values on the axis is inverted.
    `void` | `receive(ChartElementVisitor visitor)` Receives a `ChartElementVisitor`.
    `void` | `setAutoAdjustRange(boolean autoAdjust)` Sets the flag that controls whether or not the axis range is automatically updated in response to dataset changes, and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setDefaultAutoRange(Range range)` Sets the default range used when the `autoAdjustRange` flag is `true` but the dataset contains no values, and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setInverted(boolean inverted)` Sets the flag that determines whether or not the order of values on the axis is inverted, and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setLowerMargin(double margin)` Sets the size of the lower margin that will be added by the auto-range calculation and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setMarker(java.lang.String key, ValueMarker marker)` Sets the marker for the specified key and sends a change event to all registered listeners.
    `void` | `setMinAutoRangeLength(double length)` Sets the minimum length for the axis range when it is auto-calculated and sends a change event to all registered listeners.
    `void` | `setRange(double min, double max)` Sets the axis range and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setRange(Range range)` Sets the axis range (bounds) and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setTickLabelFactor(double factor)` Sets the tick label factor and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setTickLabelOffset(double offset)` Sets the tick label offset and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setTickLabelOrientation(LabelOrientation orientation)` Sets the orientation for the tick labels and sends a change event to all registered listeners.
    `void` | `setTickMarkLength(double length)` Sets the length of the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setTickMarkPaint(java.awt.Paint paint)` Sets the paint used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setTickMarkStroke(java.awt.Stroke stroke)` Sets the stroke used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setUpperMargin(double margin)` Sets the size of the upper margin that will be added by the auto-range calculation and sends an `Axis3DChangeEvent` to all registered listeners.
    `protected void` | `updateRange(Range range)` Updates the axis range (used by the auto-range calculation) without notifying listeners.

    - ### Methods inherited from class com.orsoncharts.axis.AbstractAxis3D

      `addChangeListener, draw, drawAxisLabel, fireChangeEvent, getLabel, getLabelColor, getLabelFont, getLabelOffset, getLineColor, getLineStroke, getTickLabelColor, getTickLabelFont, getTickLabelsVisible, hashCode, isVisible, markerChanged, notifyListeners, removeChangeListener, setLabel, setLabelColor, setLabelFont, setLabelOffset, setLineColor, setLineStroke, setTickLabelColor, setTickLabelFont, setTickLabelsVisible, setVisible`

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

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

    - ### Methods inherited from interface com.orsoncharts.axis.ValueAxis3D

      `generateTickData, selectTick`

    - ### Methods inherited from interface com.orsoncharts.axis.Axis3D

      `addChangeListener, draw, getLabelColor, getLabelFont, getTickLabelColor, getTickLabelFont, isVisible, removeChangeListener, setLabelColor, setLabelFont, setTickLabelColor, setTickLabelFont, setVisible, translateToWorld`

- - ### Field Detail

    - #### range

          protected Range range

      The axis range.

  - ### Constructor Detail

    - #### AbstractValueAxis3D

          public AbstractValueAxis3D(java.lang.String label,
                                     Range range)

      Creates a new axis instance.
      Parameters:
        `label` - the axis label (`null` permitted).
        `range` - the axis range (`null` not permitted).

  - ### Method Detail

    - #### getConfiguredType

          public ValueAxis3DType getConfiguredType()

      Returns the configured type for the axis.
      Specified by:
        `getConfiguredType` in interface `ValueAxis3D`
      Returns:
        The configured type (`null` if the axis has not yet been assigned to a plot).
      Since:
        1.3

    - #### axisStr

          protected java.lang.String axisStr()

      Returns a string representing the configured type of the axis.
      Specified by:
        `axisStr` in class `AbstractAxis3D`
      Returns:
        A string.

    - #### getRange

          public Range getRange()

      Returns the axis range. You can set the axis range manually or you can rely on the autoAdjustRange feature to set the axis range to match the data being plotted.
      Specified by:
        `getRange` in interface `Axis3D`
      Returns:
        the axis range (never `null`).

    - #### setRange

          public void setRange(Range range)

      Sets the axis range (bounds) and sends an `Axis3DChangeEvent` to all registered listeners.
      Specified by:
        `setRange` in interface `Axis3D`
      Parameters:
        `range` - the new range (must have positive length and `null` is not permitted).

    - #### updateRange

          protected void updateRange(Range range)

      Updates the axis range (used by the auto-range calculation) without notifying listeners.
      Parameters:
        `range` - the new range.

    - #### setRange

          public void setRange(double min,
                               double max)

      Sets the axis range and sends an `Axis3DChangeEvent` to all registered listeners.
      Specified by:
        `setRange` in interface `Axis3D`
      Parameters:
        `min` - the lower bound for the range (requires min < max).
        `max` - the upper bound for the range (requires max > min).

    - #### isAutoAdjustRange

          public boolean isAutoAdjustRange()

      Returns the flag that controls whether or not the axis range is automatically updated in response to dataset changes. The default value is `true`.
      Returns:
        A boolean.

    - #### setAutoAdjustRange

          public void setAutoAdjustRange(boolean autoAdjust)

      Sets the flag that controls whether or not the axis range is automatically updated in response to dataset changes, and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `autoAdjust` - the new flag value.

    - #### getLowerMargin

          public double getLowerMargin()

      Returns the size of the lower margin that is added by the auto-range calculation, as a percentage of the data range. This margin is used to prevent data items from being plotted right at the edges of the chart. The default value is `0.05` (five percent).
      Returns:
        The lower margin.

    - #### setLowerMargin

          public void setLowerMargin(double margin)

      Sets the size of the lower margin that will be added by the auto-range calculation and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `margin` - the margin as a percentage of the data range (0.05 = five percent).
      See Also:
        `setUpperMargin(double)`

    - #### getUpperMargin

          public double getUpperMargin()

      Returns the size of the upper margin that is added by the auto-range calculation, as a percentage of the data range. This margin is used to prevent data items from being plotted right at the edges of the chart. The default value is `0.05` (five percent).
      Returns:
        The upper margin.

    - #### setUpperMargin

          public void setUpperMargin(double margin)

      Sets the size of the upper margin that will be added by the auto-range calculation and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `margin` - the margin as a percentage of the data range (0.05 = five percent).
      See Also:
        `setLowerMargin(double)`

    - #### getDefaultAutoRange

          public Range getDefaultAutoRange()

      Returns the default range used when the `autoAdjustRange` flag is `true` but the dataset contains no values. The default range is `(0.0 to 1.0)`, depending on the context you may want to change this.
      Returns:
        The default range (never `null`).
      See Also:
        `setDefaultAutoRange(com.orsoncharts.Range)`

    - #### setDefaultAutoRange

          public void setDefaultAutoRange(Range range)

      Sets the default range used when the `autoAdjustRange` flag is `true` but the dataset contains no values, and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `range` - the range (`null` not permitted).
      See Also:
        `getDefaultAutoRange()`

    - #### getMinAutoRangeLength

          public double getMinAutoRangeLength()

      Returns the minimum length for the axis range when auto-calculated. The default value is 0.001.
      Returns:
        The minimum length.
      Since:
        1.4

    - #### setMinAutoRangeLength

          public void setMinAutoRangeLength(double length)

      Sets the minimum length for the axis range when it is auto-calculated and sends a change event to all registered listeners.
      Parameters:
        `length` - the new minimum length.
      Since:
        1.4

    - #### isInverted

          public boolean isInverted()

      Returns the flag that determines whether or not the order of values on the axis is inverted. The default value is `false`.
      Specified by:
        `isInverted` in interface `Axis3D`
      Returns:
        A boolean.
      Since:
        1.5

    - #### setInverted

          public void setInverted(boolean inverted)

      Sets the flag that determines whether or not the order of values on the axis is inverted, and sends an `Axis3DChangeEvent` to all registered listeners.
      Specified by:
        `setInverted` in interface `Axis3D`
      Parameters:
        `inverted` - the new flag value.
      Since:
        1.5

    - #### getTickLabelOrientation

          public LabelOrientation getTickLabelOrientation()

      Returns the orientation for the tick labels. The default value is `LabelOrientation.PARALLEL`.
      Returns:
        The orientation for the tick labels (never `null`).
      Since:
        1.2

    - #### setTickLabelOrientation

          public void setTickLabelOrientation(LabelOrientation orientation)

      Sets the orientation for the tick labels and sends a change event to all registered listeners. In general, `PARALLEL` is the best setting for X and Z axes, and `PERPENDICULAR` is the best setting for Y axes.
      Parameters:
        `orientation` - the orientation (`null` not permitted).
      Since:
        1.2

    - #### getTickLabelFactor

          public double getTickLabelFactor()

      Returns the tick label factor, a multiplier for the label height to determine the maximum number of tick labels that can be displayed. The default value is `1.4`.
      Returns:
        The tick label factor.

    - #### setTickLabelFactor

          public void setTickLabelFactor(double factor)

      Sets the tick label factor and sends an `Axis3DChangeEvent` to all registered listeners. This should be at least 1.0, higher values will result in larger gaps between the tick marks.
      Parameters:
        `factor` - the factor.

    - #### getTickLabelOffset

          public double getTickLabelOffset()

      Returns the tick label offset, the gap between the tick marks and the tick labels (in Java2D units). The default value is `5.0`.
      Returns:
        The tick label offset.

    - #### setTickLabelOffset

          public void setTickLabelOffset(double offset)

      Sets the tick label offset and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `offset` - the offset.

    - #### getTickMarkLength

          public double getTickMarkLength()

      Returns the length of the tick marks (in Java2D units). The default value is `3.0`.
      Returns:
        The length of the tick marks.

    - #### setTickMarkLength

          public void setTickMarkLength(double length)

      Sets the length of the tick marks and sends an `Axis3DChangeEvent` to all registered listeners. You can set this to `0.0` if you prefer no tick marks to be displayed on the axis.
      Parameters:
        `length` - the length (in Java2D units).

    - #### getTickMarkStroke

          public java.awt.Stroke getTickMarkStroke()

      Returns the stroke used to draw the tick marks. The default value is `BasicStroke(0.5f)`.
      Returns:
        The tick mark stroke (never `null`).

    - #### setTickMarkStroke

          public void setTickMarkStroke(java.awt.Stroke stroke)

      Sets the stroke used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `stroke` - the stroke (`null` not permitted).

    - #### getTickMarkPaint

          public java.awt.Paint getTickMarkPaint()

      Returns the paint used to draw the tick marks. The default value is `Color.GRAY`.
      Returns:
        The tick mark paint (never `null`).

    - #### setTickMarkPaint

          public void setTickMarkPaint(java.awt.Paint paint)

      Sets the paint used to draw the tick marks and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `paint` - the paint (`null` not permitted).

    - #### configureAsValueAxis

          public void configureAsValueAxis(CategoryPlot3D plot)

      Configures the axis to be used as the value axis for the specified plot. This method is used internally, you should not need to call it directly.
      Specified by:
        `configureAsValueAxis` in interface `ValueAxis3D`
      Parameters:
        `plot` - the plot (`null` not permitted).

    - #### configureAsXAxis

          public void configureAsXAxis(XYZPlot plot)

      Configures the axis to be used as the x-axis for the specified plot. This method is used internally, you should not need to call it directly.
      Specified by:
        `configureAsXAxis` in interface `ValueAxis3D`
      Parameters:
        `plot` - the plot (`null` not permitted).

    - #### configureAsYAxis

          public void configureAsYAxis(XYZPlot plot)

      Configures the axis to be used as the y-axis for the specified plot. This method is used internally, you should not need to call it directly.
      Specified by:
        `configureAsYAxis` in interface `ValueAxis3D`
      Parameters:
        `plot` - the plot (`null` not permitted).

    - #### configureAsZAxis

          public void configureAsZAxis(XYZPlot plot)

      Configures the axis to be used as the z-axis for the specified plot. This method is used internally, you should not need to call it directly.
      Specified by:
        `configureAsZAxis` in interface `ValueAxis3D`
      Parameters:
        `plot` - the plot (`null` not permitted).

    - #### adjustedDataRange

          protected abstract Range adjustedDataRange(Range range)

      Adjusts the range by adding the lower and upper margins and taking into account any other settings.
      Parameters:
        `range` - the range (`null` not permitted).
      Returns:
        The adjusted range.

    - #### getMarker

          public ValueMarker getMarker(java.lang.String key)

      Returns the marker with the specified key, if there is one.
      Specified by:
        `getMarker` in interface `ValueAxis3D`
      Parameters:
        `key` - the key (`null` not permitted).
      Returns:
        The marker (possibly `null`).
      Since:
        1.2

    - #### setMarker

          public void setMarker(java.lang.String key,
                                ValueMarker marker)

      Sets the marker for the specified key and sends a change event to all registered listeners. If there is an existing marker it is replaced (the axis will no longer listen for change events on the previous marker).
      Parameters:
        `key` - the key that identifies the marker (`null` not permitted).
        `marker` - the marker (`null` permitted).
      Since:
        1.2

    - #### getMarkers

          public java.util.Map<java.lang.String,ValueMarker> getMarkers()

      Returns a new map containing the markers assigned to this axis.
      Returns:
        A map.
      Since:
        1.2

    - #### generateMarkerData

          public java.util.List<MarkerData> generateMarkerData()

      Generates and returns a list of marker data items for the axis.
      Specified by:
        `generateMarkerData` in interface `ValueAxis3D`
      Returns:
        A list of marker data items (never `null`).

    - #### receive

          public void receive(ChartElementVisitor visitor)

      Receives a `ChartElementVisitor`. This method is part of a general mechanism for traversing the chart structure and performing operations on each element in the chart. You will not normally call this method directly.
      Specified by:
        `receive` in interface `ChartElement`
      Specified by:
        `receive` in class `AbstractAxis3D`
      Parameters:
        `visitor` - the visitor (`null` not permitted).
      Since:
        1.2

    - #### equals

          public boolean equals(java.lang.Object obj)

      Description copied from class: `AbstractAxis3D`
      Tests this instance for equality with an arbitrary object.
      Overrides:
        `equals` in class `AbstractAxis3D`
      Parameters:
        `obj` - the object to test against (`null` permitted).
      Returns:
        A boolean.