Class CategoryAxis

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    Direct Known Subclasses:
    ExtendedCategoryAxis, SubCategoryAxis

    public class CategoryAxis
    extends Axis
    implements java.lang.Cloneable, java.io.Serializable
    An axis that displays categories.
    See Also:
    Serialized Form
    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        For serialization.
        See Also:
        Constant Field Values
      • DEFAULT_AXIS_MARGIN

        public static final double DEFAULT_AXIS_MARGIN
        The default margin for the axis (used for both lower and upper margins).
        See Also:
        Constant Field Values
      • DEFAULT_CATEGORY_MARGIN

        public static final double DEFAULT_CATEGORY_MARGIN
        The default margin between categories (a percentage of the overall axis length).
        See Also:
        Constant Field Values
      • lowerMargin

        private double lowerMargin
        The amount of space reserved at the start of the axis.
      • upperMargin

        private double upperMargin
        The amount of space reserved at the end of the axis.
      • categoryMargin

        private double categoryMargin
        The amount of space reserved between categories.
      • maximumCategoryLabelLines

        private int maximumCategoryLabelLines
        The maximum number of lines for category labels.
      • maximumCategoryLabelWidthRatio

        private float maximumCategoryLabelWidthRatio
        A ratio that is multiplied by the width of one category to determine the maximum label width.
      • categoryLabelPositionOffset

        private int categoryLabelPositionOffset
        The category label offset.
      • categoryLabelPositions

        private CategoryLabelPositions categoryLabelPositions
        A structure defining the category label positions for each axis location.
      • tickLabelFontMap

        private java.util.Map tickLabelFontMap
        Storage for tick label font overrides (if any).
      • tickLabelPaintMap

        private transient java.util.Map tickLabelPaintMap
        Storage for tick label paint overrides (if any).
      • categoryLabelToolTips

        private java.util.Map categoryLabelToolTips
        Storage for the category label tooltips (if any).
      • categoryLabelURLs

        private java.util.Map categoryLabelURLs
        Storage for the category label URLs (if any).
    • Constructor Detail

      • CategoryAxis

        public CategoryAxis()
        Creates a new category axis with no label.
      • CategoryAxis

        public CategoryAxis​(java.lang.String label)
        Constructs a category axis, using default values where necessary.
        Parameters:
        label - the axis label (null permitted).
    • Method Detail

      • setLowerMargin

        public void setLowerMargin​(double margin)
        Sets the lower margin for the axis and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        margin - the margin as a percentage of the axis length (for example, 0.05 is five percent).
        See Also:
        getLowerMargin()
      • setUpperMargin

        public void setUpperMargin​(double margin)
        Sets the upper margin for the axis and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        margin - the margin as a percentage of the axis length (for example, 0.05 is five percent).
        See Also:
        getUpperMargin()
      • getCategoryMargin

        public double getCategoryMargin()
        Returns the category margin.
        Returns:
        The margin.
        See Also:
        setCategoryMargin(double)
      • setCategoryMargin

        public void setCategoryMargin​(double margin)
        Sets the category margin and sends an AxisChangeEvent to all registered listeners. The overall category margin is distributed over N-1 gaps, where N is the number of categories on the axis.
        Parameters:
        margin - the margin as a percentage of the axis length (for example, 0.05 is five percent).
        See Also:
        getCategoryMargin()
      • getMaximumCategoryLabelLines

        public int getMaximumCategoryLabelLines()
        Returns the maximum number of lines to use for each category label.
        Returns:
        The maximum number of lines.
        See Also:
        setMaximumCategoryLabelLines(int)
      • setMaximumCategoryLabelLines

        public void setMaximumCategoryLabelLines​(int lines)
        Sets the maximum number of lines to use for each category label and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        lines - the maximum number of lines.
        See Also:
        getMaximumCategoryLabelLines()
      • setMaximumCategoryLabelWidthRatio

        public void setMaximumCategoryLabelWidthRatio​(float ratio)
        Sets the maximum category label width ratio and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        ratio - the ratio.
        See Also:
        getMaximumCategoryLabelWidthRatio()
      • getCategoryLabelPositionOffset

        public int getCategoryLabelPositionOffset()
        Returns the offset between the axis and the category labels (before label positioning is taken into account).
        Returns:
        The offset (in Java2D units).
        See Also:
        setCategoryLabelPositionOffset(int)
      • setCategoryLabelPositionOffset

        public void setCategoryLabelPositionOffset​(int offset)
        Sets the offset between the axis and the category labels (before label positioning is taken into account) and sends a change event to all registered listeners.
        Parameters:
        offset - the offset (in Java2D units).
        See Also:
        getCategoryLabelPositionOffset()
      • setCategoryLabelPositions

        public void setCategoryLabelPositions​(CategoryLabelPositions positions)
        Sets the category label position specification for the axis and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        positions - the positions (null not permitted).
        See Also:
        getCategoryLabelPositions()
      • getTickLabelFont

        public java.awt.Font getTickLabelFont​(java.lang.Comparable category)
        Returns the font for the tick label for the given category.
        Parameters:
        category - the category (null not permitted).
        Returns:
        The font (never null).
        See Also:
        setTickLabelFont(Comparable, Font)
      • setTickLabelFont

        public void setTickLabelFont​(java.lang.Comparable category,
                                     java.awt.Font font)
        Sets the font for the tick label for the specified category and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        category - the category (null not permitted).
        font - the font (null permitted).
        See Also:
        getTickLabelFont(Comparable)
      • getTickLabelPaint

        public java.awt.Paint getTickLabelPaint​(java.lang.Comparable category)
        Returns the paint for the tick label for the given category.
        Parameters:
        category - the category (null not permitted).
        Returns:
        The paint (never null).
        See Also:
        Axis.setTickLabelPaint(Paint)
      • setTickLabelPaint

        public void setTickLabelPaint​(java.lang.Comparable category,
                                      java.awt.Paint paint)
        Sets the paint for the tick label for the specified category and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        category - the category (null not permitted).
        paint - the paint (null permitted).
        See Also:
        getTickLabelPaint(Comparable)
      • addCategoryLabelToolTip

        public void addCategoryLabelToolTip​(java.lang.Comparable category,
                                            java.lang.String tooltip)
        Adds a tooltip to the specified category and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        category - the category (null not permitted).
        tooltip - the tooltip text (null permitted).
        See Also:
        removeCategoryLabelToolTip(Comparable)
      • addCategoryLabelURL

        public void addCategoryLabelURL​(java.lang.Comparable category,
                                        java.lang.String url)
        Adds a URL (to be used in image maps) to the specified category and sends an AxisChangeEvent to all registered listeners.
        Parameters:
        category - the category (null not permitted).
        url - the URL text (null permitted).
        See Also:
        removeCategoryLabelURL(Comparable)
      • getCategoryJava2DCoordinate

        public double getCategoryJava2DCoordinate​(CategoryAnchor anchor,
                                                  int category,
                                                  int categoryCount,
                                                  java.awt.geom.Rectangle2D area,
                                                  RectangleEdge edge)
        Returns the Java 2D coordinate for a category.
        Parameters:
        anchor - the anchor point.
        category - the category index.
        categoryCount - the category count.
        area - the data area.
        edge - the location of the axis.
        Returns:
        The coordinate.
      • getCategoryMiddle

        public double getCategoryMiddle​(java.lang.Comparable category,
                                        java.util.List categories,
                                        java.awt.geom.Rectangle2D area,
                                        RectangleEdge edge)
        A convenience method that returns the axis coordinate for the centre of a category.
        Parameters:
        category - the category key (null not permitted).
        categories - the categories (null not permitted).
        area - the data area (null not permitted).
        edge - the edge along which the axis lies (null not permitted).
        Returns:
        The centre coordinate.
        See Also:
        getCategorySeriesMiddle(Comparable, Comparable, CategoryDataset, double, Rectangle2D, RectangleEdge)
      • getCategorySeriesMiddle

        public double getCategorySeriesMiddle​(java.lang.Comparable category,
                                              java.lang.Comparable seriesKey,
                                              CategoryDataset dataset,
                                              double itemMargin,
                                              java.awt.geom.Rectangle2D area,
                                              RectangleEdge edge)
        Returns the middle coordinate (in Java2D space) for a series within a category.
        Parameters:
        category - the category (null not permitted).
        seriesKey - the series key (null not permitted).
        dataset - the dataset (null not permitted).
        itemMargin - the item margin (0.0 <= itemMargin < 1.0);
        area - the area (null not permitted).
        edge - the edge (null not permitted).
        Returns:
        The coordinate in Java2D space.
      • getCategorySeriesMiddle

        public double getCategorySeriesMiddle​(int categoryIndex,
                                              int categoryCount,
                                              int seriesIndex,
                                              int seriesCount,
                                              double itemMargin,
                                              java.awt.geom.Rectangle2D area,
                                              RectangleEdge edge)
        Returns the middle coordinate (in Java2D space) for a series within a category.
        Parameters:
        categoryIndex - the category index.
        categoryCount - the category count.
        seriesIndex - the series index.
        seriesCount - the series count.
        itemMargin - the item margin (0.0 <= itemMargin < 1.0);
        area - the area (null not permitted).
        edge - the edge (null not permitted).
        Returns:
        The coordinate in Java2D space.
      • calculateCategorySize

        protected double calculateCategorySize​(int categoryCount,
                                               java.awt.geom.Rectangle2D area,
                                               RectangleEdge edge)
        Calculates the size (width or height, depending on the location of the axis) of a category.
        Parameters:
        categoryCount - the number of categories.
        area - the area within which the categories will be drawn.
        edge - the axis location.
        Returns:
        The category size.
      • calculateCategoryGapSize

        protected double calculateCategoryGapSize​(int categoryCount,
                                                  java.awt.geom.Rectangle2D area,
                                                  RectangleEdge edge)
        Calculates the size (width or height, depending on the location of the axis) of a category gap.
        Parameters:
        categoryCount - the number of categories.
        area - the area within which the categories will be drawn.
        edge - the axis location.
        Returns:
        The category gap width.
      • reserveSpace

        public AxisSpace reserveSpace​(java.awt.Graphics2D g2,
                                      Plot plot,
                                      java.awt.geom.Rectangle2D plotArea,
                                      RectangleEdge edge,
                                      AxisSpace space)
        Estimates the space required for the axis, given a specific drawing area.
        Specified by:
        reserveSpace in class Axis
        Parameters:
        g2 - the graphics device (used to obtain font information).
        plot - the plot that the axis belongs to.
        plotArea - the area within which the axis should be drawn.
        edge - the axis location (top or bottom).
        space - the space already reserved.
        Returns:
        The space required to draw the axis.
      • configure

        public void configure()
        Configures the axis against the current plot.
        Specified by:
        configure in class Axis
      • draw

        public AxisState draw​(java.awt.Graphics2D g2,
                              double cursor,
                              java.awt.geom.Rectangle2D plotArea,
                              java.awt.geom.Rectangle2D dataArea,
                              RectangleEdge edge,
                              PlotRenderingInfo plotState)
        Draws the axis on a Java 2D graphics device (such as the screen or a printer).
        Specified by:
        draw in class Axis
        Parameters:
        g2 - the graphics device (null not permitted).
        cursor - the cursor location.
        plotArea - the area within which the axis should be drawn (null not permitted).
        dataArea - the area within which the plot is being drawn (null not permitted).
        edge - the location of the axis (null not permitted).
        plotState - collects information about the plot (null permitted).
        Returns:
        The axis state (never null).
      • drawCategoryLabels

        protected AxisState drawCategoryLabels​(java.awt.Graphics2D g2,
                                               java.awt.geom.Rectangle2D plotArea,
                                               java.awt.geom.Rectangle2D dataArea,
                                               RectangleEdge edge,
                                               AxisState state,
                                               PlotRenderingInfo plotState)
        Draws the category labels and returns the updated axis state.
        Parameters:
        g2 - the graphics device (null not permitted).
        plotArea - the plot area (null not permitted).
        dataArea - the area inside the axes (null not permitted).
        edge - the axis location (null not permitted).
        state - the axis state (null not permitted).
        plotState - collects information about the plot (null permitted).
        Returns:
        The updated axis state (never null).
      • refreshTicks

        public java.util.List refreshTicks​(java.awt.Graphics2D g2,
                                           AxisState state,
                                           java.awt.geom.Rectangle2D dataArea,
                                           RectangleEdge edge)
        Creates a temporary list of ticks that can be used when drawing the axis.
        Specified by:
        refreshTicks in class Axis
        Parameters:
        g2 - the graphics device (used to get font measurements).
        state - the axis state.
        dataArea - the area inside the axes.
        edge - the location of the axis.
        Returns:
        A list of ticks.
      • drawTickMarks

        public void drawTickMarks​(java.awt.Graphics2D g2,
                                  double cursor,
                                  java.awt.geom.Rectangle2D dataArea,
                                  RectangleEdge edge,
                                  AxisState state)
        Draws the tick marks.
        Parameters:
        g2 - the graphics target.
        cursor - the cursor position (an offset when drawing multiple axes)
        dataArea - the area for plotting the data.
        edge - the location of the axis.
        state - the axis state.
      • createLabel

        protected TextBlock createLabel​(java.lang.Comparable category,
                                        float width,
                                        RectangleEdge edge,
                                        java.awt.Graphics2D g2)
        Creates a label.
        Parameters:
        category - the category.
        width - the available width.
        edge - the edge on which the axis appears.
        g2 - the graphics device.
        Returns:
        A label.
      • calculateTextBlockWidth

        protected double calculateTextBlockWidth​(TextBlock block,
                                                 CategoryLabelPosition position,
                                                 java.awt.Graphics2D g2)
        A utility method for determining the width of a text block.
        Parameters:
        block - the text block.
        position - the position.
        g2 - the graphics device.
        Returns:
        The width.
      • calculateTextBlockHeight

        protected double calculateTextBlockHeight​(TextBlock block,
                                                  CategoryLabelPosition position,
                                                  java.awt.Graphics2D g2)
        A utility method for determining the height of a text block.
        Parameters:
        block - the text block.
        position - the label position.
        g2 - the graphics device.
        Returns:
        The height.
      • clone

        public java.lang.Object clone()
                               throws java.lang.CloneNotSupportedException
        Creates a clone of the axis.
        Overrides:
        clone in class Axis
        Returns:
        A clone.
        Throws:
        java.lang.CloneNotSupportedException - if some component of the axis does not support cloning.
      • equals

        public boolean equals​(java.lang.Object obj)
        Tests this axis for equality with an arbitrary object.
        Overrides:
        equals in class Axis
        Parameters:
        obj - the object (null permitted).
        Returns:
        A boolean.
      • hashCode

        public int hashCode()
        Returns a hash code for this object.
        Overrides:
        hashCode in class Axis
        Returns:
        A hash code.
      • writeObject

        private void writeObject​(java.io.ObjectOutputStream stream)
                          throws java.io.IOException
        Provides serialization support.
        Parameters:
        stream - the output stream.
        Throws:
        java.io.IOException - if there is an I/O error.
      • readObject

        private void readObject​(java.io.ObjectInputStream stream)
                         throws java.io.IOException,
                                java.lang.ClassNotFoundException
        Provides serialization support.
        Parameters:
        stream - the input stream.
        Throws:
        java.io.IOException - if there is an I/O error.
        java.lang.ClassNotFoundException - if there is a classpath problem.
      • readPaintMap

        private java.util.Map readPaintMap​(java.io.ObjectInputStream in)
                                    throws java.io.IOException,
                                           java.lang.ClassNotFoundException
        Reads a Map of (Comparable, Paint) elements from a stream.
        Parameters:
        in - the input stream.
        Returns:
        The map.
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException
        See Also:
        writePaintMap(Map, ObjectOutputStream)
      • writePaintMap

        private void writePaintMap​(java.util.Map map,
                                   java.io.ObjectOutputStream out)
                            throws java.io.IOException
        Writes a map of (Comparable, Paint) elements to a stream.
        Parameters:
        map - the map (null permitted).
        out -
        Throws:
        java.io.IOException
        See Also:
        readPaintMap(ObjectInputStream)
      • equalPaintMaps

        private boolean equalPaintMaps​(java.util.Map map1,
                                       java.util.Map map2)
        Tests two maps containing (Comparable, Paint) elements for equality.
        Parameters:
        map1 - the first map (null not permitted).
        map2 - the second map (null not permitted).
        Returns:
        A boolean.