com.orsoncharts.axis

## Class StandardCategoryAxis3D

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

- All Implemented Interfaces:
    Axis3D, CategoryAxis3D, ChartElement, MarkerChangeListener, java.io.Serializable, java.util.EventListener

      public class StandardCategoryAxis3D
      extends AbstractAxis3D
      implements CategoryAxis3D, java.io.Serializable

  An axis that displays categories.
  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 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
    `StandardCategoryAxis3D()` Default constructor.
    `StandardCategoryAxis3D(java.lang.String label)` Creates a new axis with the specified label.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected java.lang.String` | `axisStr()` Returns "row" if the axis has been configured as a row axis, "column" if the axis has been configured as a column axis, and the empty string ("") if the axis has not yet been configured.
    `void` | `configureAsColumnAxis(CategoryPlot3D plot)` Configures the axis to be used as a column axis for the specified plot.
    `void` | `configureAsRowAxis(CategoryPlot3D plot)` Configures the axis to be used as a row axis for the specified plot.
    `void` | `draw(java.awt.Graphics2D g2, java.awt.geom.Point2D pt0, java.awt.geom.Point2D pt1, java.awt.geom.Point2D opposingPt, java.util.List<TickData> tickData, RenderingInfo info, boolean hinting)` Draws the axis between the two points `pt0` and `pt1` in Java2D space.
    `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.
    `java.util.List<TickData>` | `generateTickDataForColumns(CategoryDataset3D dataset)` Generates the tick data for the axis (assumes the axis is being used as the row axis).
    `java.util.List<TickData>` | `generateTickDataForRows(CategoryDataset3D dataset)` Generates the tick data for the axis (assumes the axis is being used as the row axis).
    `double` | `getCategoryValue(java.lang.Comparable<?> category)` Returns the value for the specified category, or `Double.NaN` if the category is not registered on the axis.
    `double` | `getCategoryWidth()` Returns the width of a single category in the units of the axis range.
    `double` | `getLowerMargin()` Returns the margin to leave at the lower end of the axis, as a percentage of the axis length.
    `CategoryMarker` | `getMarker(java.lang.String key)` Returns the marker with the specified key, if there is one.
    `java.util.Map<java.lang.String,CategoryMarker>` | `getMarkers()` Returns a new map containing the markers that are assigned to this axis.
    `int` | `getMaxTickLabelLevels()` Returns the maximum number of offset levels for the category labels on the axis.
    `Range` | `getRange()` Returns the range for the axis.
    `double` | `getTickLabelFactor()` Returns the tick label factor.
    `CategoryLabelGenerator` | `getTickLabelGenerator()` Returns the tick label generator for the axis.
    `double` | `getTickLabelOffset()` Returns the offset between the tick marks and the tick labels.
    `LabelOrientation` | `getTickLabelOrientation()` Returns the orientation for the tick labels.
    `double` | `getTickMarkLength()` Returns the tick mark length (in Java2D units).
    `java.awt.Paint` | `getTickMarkPaint()` Returns the paint used to draw the tick marks, if they are visible.
    `java.awt.Stroke` | `getTickMarkStroke()` Returns the stroke used to draw the tick marks, if they are visible.
    `double` | `getUpperMargin()` Returns the margin to leave at the upper end of the axis, as a percentage of the axis length.
    `boolean` | `isColumnAxis()` Returns `true` if this axis has been configured as a column axis for the plot that it belongs to, and `false` otherwise.
    `boolean` | `isFirstCategoryHalfWidth()` Returns `true` if the first category on the axis should occupy half the normal width, and `false` otherwise.
    `boolean` | `isInverted()` Returns `true` if the axis inverts the order of the data items, and `false` otherwise.
    `boolean` | `isLastCategoryHalfWidth()` Returns `true` if the last category on the axis should occupy half the normal width, and `false` otherwise.
    `boolean` | `isRowAxis()` Returns `true` if this axis has been configured as a row axis for the plot that it belongs to, and `false` otherwise.
    `void` | `receive(ChartElementVisitor visitor)` Receives a `ChartElementVisitor`.
    `void` | `setFirstCategoryHalfWidth(boolean half)` Sets the flag that controls whether the first category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setInverted(boolean inverted)` Sets the flag that controls whether or not the axis inverts the order of the data items and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setLastCategoryHalfWidth(boolean half)` Sets the flag that controls whether the last category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setLowerMargin(double margin)` Sets the margin to leave at the lower end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setMarker(java.lang.String key, CategoryMarker marker)` Sets the marker for the specified key and sends a change event to all registered listeners.
    `void` | `setMaxTickLabelLevels(int levels)` Sets the maximum number of offset levels for the category labels on the axis and sends a change event to all registered listeners.
    `void` | `setRange(double lowerBound, double upperBound)` Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setRange(Range range)` Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners.
    `void` | `setTickLabelFactor(double factor)` Sets the tick label factor and sends a change event to all registered listeners.
    `void` | `setTickLabelGenerator(CategoryLabelGenerator generator)` Sets the tick label generator for the axis and sends a change event to all registered listeners.
    `void` | `setTickLabelOffset(double offset)` Sets the offset between the tick marks and the tick labels and sends a `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 tick mark length (in Java2D units) 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 margin to leave at the upper end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.
    `double` | `translateToWorld(double value, double length)` Translates a value on the axis to the equivalent coordinate in the 3D world used to construct a model of the chart.

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

      `addChangeListener, 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.Axis3D

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

- - ### Constructor Detail

    - #### StandardCategoryAxis3D

          public StandardCategoryAxis3D()

      Default constructor.

    - #### StandardCategoryAxis3D

          public StandardCategoryAxis3D(java.lang.String label)

      Creates a new axis with the specified label.
      Parameters:
        `label` - the axis label (`null` permitted).

  - ### Method Detail

    - #### isRowAxis

          public boolean isRowAxis()

      Returns `true` if this axis has been configured as a row axis for the plot that it belongs to, and `false` otherwise.
      Specified by:
        `isRowAxis` in interface `CategoryAxis3D`
      Returns:
        A boolean.
      Since:
        1.3

    - #### isColumnAxis

          public boolean isColumnAxis()

      Returns `true` if this axis has been configured as a column axis for the plot that it belongs to, and `false` otherwise.
      Specified by:
        `isColumnAxis` in interface `CategoryAxis3D`
      Returns:
        A boolean.
      Since:
        1.3

    - #### getRange

          public Range getRange()

      Returns the range for the axis. By convention, the category axes have a range from 0.0 to 1.0.
      Specified by:
        `getRange` in interface `Axis3D`
      Returns:
        The range.

    - #### setRange

          public void setRange(double lowerBound,
                               double upperBound)

      Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners.
      Specified by:
        `setRange` in interface `Axis3D`
      Parameters:
        `lowerBound` - the lower bound.
        `upperBound` - the upper bound.

    - #### setRange

          public void setRange(Range range)

      Sets the range for the axis and sends an `Axis3DChangeEvent` to all registered listeners. Note that changing the range for the category axis will have no visible effect.
      Specified by:
        `setRange` in interface `Axis3D`
      Parameters:
        `range` - the range (`null` not permitted).

    - #### getLowerMargin

          public double getLowerMargin()

      Returns the margin to leave at the lower end of the axis, as a percentage of the axis length. The default is `0.05` (five percent).
      Returns:
        The lower margin.

    - #### setLowerMargin

          public void setLowerMargin(double margin)

      Sets the margin to leave at the lower end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `margin` - the margin.

    - #### getUpperMargin

          public double getUpperMargin()

      Returns the margin to leave at the upper end of the axis, as a percentage of the axis length. The default is `0.05` (five percent).
      Returns:
        The lower margin.

    - #### setUpperMargin

          public void setUpperMargin(double margin)

      Sets the margin to leave at the upper end of the axis and sends an `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `margin` - the margin.

    - #### isFirstCategoryHalfWidth

          public boolean isFirstCategoryHalfWidth()

      Returns `true` if the first category on the axis should occupy half the normal width, and `false` otherwise.
      Returns:
        A boolean.
      See Also:
        `setFirstCategoryHalfWidth(boolean)`

    - #### setFirstCategoryHalfWidth

          public void setFirstCategoryHalfWidth(boolean half)

      Sets the flag that controls whether the first category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners. There are some renderers where the charts look better when half-widths are used (for example, `AreaRenderer3D`).
      Parameters:
        `half` - half width?
      See Also:
        `setLastCategoryHalfWidth(boolean)`

    - #### isLastCategoryHalfWidth

          public boolean isLastCategoryHalfWidth()

      Returns `true` if the last category on the axis should occupy half the normal width, and `false` otherwise.
      Returns:
        A boolean.
      See Also:
        `setLastCategoryHalfWidth(boolean)`

    - #### setLastCategoryHalfWidth

          public void setLastCategoryHalfWidth(boolean half)

      Sets the flag that controls whether the last category on the axis occupies a full or half width, and sends an `Axis3DChangeEvent` to all registered listeners. There are some renderers where the charts look better when half-widths are used (for example, `AreaRenderer3D`).
      Parameters:
        `half` - half width?
      See Also:
        `setFirstCategoryHalfWidth(boolean)`

    - #### getTickMarkLength

          public double getTickMarkLength()

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

    - #### setTickMarkLength

          public void setTickMarkLength(double length)

      Sets the tick mark length (in Java2D units) and sends an `Axis3DChangeEvent` to all registered listeners. You can set the length to `0.0` if you don't want any tick marks on the axis.
      Parameters:
        `length` - the length (in Java2D units).

    - #### getTickMarkPaint

          public java.awt.Paint getTickMarkPaint()

      Returns the paint used to draw the tick marks, if they are visible. The default value is `Color.GRAY`.
      Returns:
        The paint used to draw the tick marks (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).

    - #### getTickMarkStroke

          public java.awt.Stroke getTickMarkStroke()

      Returns the stroke used to draw the tick marks, if they are visible. The default value is `new BasicStroke(0.5f)`.
      Returns:
        The stroke used to draw the tick marks (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).

    - #### getTickLabelGenerator

          public CategoryLabelGenerator getTickLabelGenerator()

      Returns the tick label generator for the axis. This is an object that is responsible for creating the category labels on the axis. You can plug in your own instance to take full control over the generation of category labels.
      Returns:
        The tick label generator for the axis (never `null`).
      Since:
        1.2

    - #### setTickLabelGenerator

          public void setTickLabelGenerator(CategoryLabelGenerator generator)

      Sets the tick label generator for the axis and sends a change event to all registered listeners.
      Parameters:
        `generator` - the generator (`null` not permitted).
      Since:
        1.2

    - #### getTickLabelOffset

          public double getTickLabelOffset()

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

    - #### setTickLabelOffset

          public void setTickLabelOffset(double offset)

      Sets the offset between the tick marks and the tick labels and sends a `Axis3DChangeEvent` to all registered listeners.
      Parameters:
        `offset` - the offset.

    - #### 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.
      Parameters:
        `orientation` - the orientation (`null` not permitted).
      Since:
        1.2

    - #### getMaxTickLabelLevels

          public int getMaxTickLabelLevels()

      Returns the maximum number of offset levels for the category labels on the axis. The default value is 3.
      Returns:
        The maximum number of offset levels.
      Since:
        1.2

    - #### setMaxTickLabelLevels

          public void setMaxTickLabelLevels(int levels)

      Sets the maximum number of offset levels for the category labels on the axis and sends a change event to all registered listeners.
      Parameters:
        `levels` - the maximum number of levels.
      Since:
        1.2

    - #### getTickLabelFactor

          public double getTickLabelFactor()

      Returns the tick label factor. The default value is `1.4`.
      Returns:
        The tick label factor.
      Since:
        1.2

    - #### setTickLabelFactor

          public void setTickLabelFactor(double factor)

      Sets the tick label factor and sends a change event to all registered listeners.
      Parameters:
        `factor` - the new factor (should be at least 1.0).
      Since:
        1.2

    - #### getMarker

          public CategoryMarker getMarker(java.lang.String key)

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

    - #### setMarker

          public void setMarker(java.lang.String key,
                                CategoryMarker 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 (and 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,CategoryMarker> getMarkers()

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

    - #### getCategoryWidth

          public double getCategoryWidth()

      Returns the width of a single category in the units of the axis range.
      Specified by:
        `getCategoryWidth` in interface `CategoryAxis3D`
      Returns:
        The width of a single category.

    - #### configureAsRowAxis

          public void configureAsRowAxis(CategoryPlot3D plot)

      Configures the axis to be used as a row axis for the specified plot. This method is for internal use, you should not call it directly.
      Specified by:
        `configureAsRowAxis` in interface `CategoryAxis3D`
      Parameters:
        `plot` - the plot (`null` not permitted).

    - #### configureAsColumnAxis

          public void configureAsColumnAxis(CategoryPlot3D plot)

      Configures the axis to be used as a column axis for the specified plot. This method is for internal use, you won't normally need to call it directly.
      Specified by:
        `configureAsColumnAxis` in interface `CategoryAxis3D`
      Parameters:
        `plot` - the plot (`null` not permitted).

    - #### getCategoryValue

          public double getCategoryValue(java.lang.Comparable<?> category)

      Returns the value for the specified category, or `Double.NaN` if the category is not registered on the axis.
      Specified by:
        `getCategoryValue` in interface `CategoryAxis3D`
      Parameters:
        `category` - the category (`null` not permitted).
      Returns:
        The value.

    - #### translateToWorld

          public double translateToWorld(double value,
                                         double length)

      Translates a value on the axis to the equivalent coordinate in the 3D world used to construct a model of the chart.
      Specified by:
        `translateToWorld` in interface `Axis3D`
      Parameters:
        `value` - the value along the axis.
        `length` - the length of one side of the 3D box containing the model.
      Returns:
        A coordinate in 3D space.

    - #### draw

          public void draw(java.awt.Graphics2D g2,
                           java.awt.geom.Point2D pt0,
                           java.awt.geom.Point2D pt1,
                           java.awt.geom.Point2D opposingPt,
                           java.util.List<TickData> tickData,
                           RenderingInfo info,
                           boolean hinting)

      Draws the axis between the two points `pt0` and `pt1` in Java2D space.
      Specified by:
        `draw` in interface `Axis3D`
      Specified by:
        `draw` in class `AbstractAxis3D`
      Parameters:
        `g2` - the graphics target (`null` not permitted).
        `pt0` - the starting point for the axis (`null` not permitted).
        `pt1` - the ending point for the axis (`null` not permitted).
        `opposingPt` - a point on the opposite side of the line from the labels (`null` not permitted).
        `tickData` - the tick data, contains positioning anchors calculated by the 3D engine (`null` not permitted).
        `info` - an object to be populated with rendering info (`null` permitted).
        `hinting` - perform element hinting?

    - #### axisStr

          protected java.lang.String axisStr()

      Returns "row" if the axis has been configured as a row axis, "column" if the axis has been configured as a column axis, and the empty string ("") if the axis has not yet been configured.
      Specified by:
        `axisStr` in class `AbstractAxis3D`
      Returns:
        A string (never `null`).
      Since:
        1.3

    - #### generateTickDataForRows

          public java.util.List<TickData> generateTickDataForRows(CategoryDataset3D dataset)

      Generates the tick data for the axis (assumes the axis is being used as the row axis). The dataset is passed as an argument to provide the opportunity to incorporate dataset-specific info into tick labels (for example, a row label might show the total for that row in the dataset) ---whether or not this is used depends on the axis implementation.
      Specified by:
        `generateTickDataForRows` in interface `CategoryAxis3D`
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The tick data.
      Since:
        1.2

    - #### generateTickDataForColumns

          public java.util.List<TickData> generateTickDataForColumns(CategoryDataset3D dataset)

      Generates the tick data for the axis (assumes the axis is being used as the row axis). The dataset is passed as an argument to provide the opportunity to incorporate dataset-specific info into tick labels (for example, a row label might show the total for that row in the dataset) ---whether or not this is used depends on the axis implementation.
      Specified by:
        `generateTickDataForColumns` in interface `CategoryAxis3D`
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The tick data.
      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 `CategoryAxis3D`
      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)

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

    - #### isInverted

          public boolean isInverted()

      Returns `true` if the axis inverts the order of the data items, and `false` otherwise.
      Specified by:
        `isInverted` in interface `Axis3D`
      Returns:
        A boolean.
      Since:
        1.5

    - #### setInverted

          public void setInverted(boolean inverted)

      Sets the flag that controls whether or not the axis inverts the order of the data items and sends an `Axis3DChangeEvent` to all registered listeners.
      Specified by:
        `setInverted` in interface `Axis3D`
      Parameters:
        `inverted` - the new flag value.
      Since:
        1.5