Class AxisBuilder<T extends Graph.Axis>

java.lang.Object
org.bzdev.graphs.AxisBuilder<T>
Direct Known Subclasses:
AxisBuilder.ClockTime, AxisBuilder.Linear, AxisBuilder.Log

public abstract class AxisBuilder<T extends Graph.Axis> extends Object
Base class for axis builders. In addition to some methods shared by all subclasses, this class provides a number of protected fields that contain configuration data used by subclasses. These fields should be treated as read only.

The classes Graph.Axis and Graph.TickSpec can be used directly to create an axis. The subclasses of AxisBuilder provide a simpler API for common cases.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    AxisBuilder for axes that use a combination of hours, minutes, and seconds.
    static final class 
    AxisBuilder for a linear axis.
    static class 
    AxisBuilder for a log axis.
    static enum 
    Spacings between similar tick marks for the class AxisBuilder.ClockTime.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected double
    The axis scale.
    protected Color
    The color for an axis.
    protected boolean
    The orientation of the tick marks.
    protected Graph.Axis.Dir
    The direction of the graph.
    protected Graph.FontParms
    The fontParms for this axis.
    protected Graph
    The graph on which an axis will be drawn.
    protected String
    The label for an axis; null if there is no label.
    protected double
    The separation from an axis label and the tick marks or tick-mark labels.
    protected double[]
    For each level, this number provides the separation in user-space units between tick labels and tick marks.
    protected double
    The length of the axis.
    protected double[]
    For each level, this array provides the number by which to multiple the axis width (in user-space units) to obtain the tick-mark length.
    protected double[]
    For each level, this array provides the number by which to multiple the axis width (in user-space units) to obtain the tick-mark width.
    protected double
    The value of the graph's range that is closest to the left or lower edge of the graph (excluding offsets).
    protected double
    The length in user space of the offset.
    protected double
    The starting X position for the axis in graph coordinate space.
    protected double
    The starting Y position for the axis in graph coordinate space.
    protected double
    The length of the graph in graph coordinate space and in the direction of the axis, excluding the offsets.
    protected boolean
    Indicate if tick labels are constrained to be horizontal.
    protected double
    The value of the graph's range that is closest to the right or upper edge of the graph (excluding offsets).
    protected double
    The length of a graph in user space and in the direction of the axis, excluding the offsets.
    protected double
    The width of the axis.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AxisBuilder(Graph g, double startX, double startY, double length, boolean horizontal, boolean flip, String label)
    Constructor with a "flip" option.
    protected
    AxisBuilder(Graph g, double startX, double startY, double length, boolean horizontal, String label)
    Constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    configureLevels(double[] lengths, double[] widths, double[] labelSeps)
    Configure levels.
    abstract T
    Create an axis.
    double
    Get the axis scale.
    double
    Get the offset for a label.
    int
    Get the number of levels.
    double
    getTickScaling(double axisWidth)
    Get the scaling factor applied to tick-mark dimensions for a given axis width.
    double
    Get the tick-scaling factor.
    protected abstract T
    newAxisInstance(double startX, double startY, Graph.Axis.Dir direction, double length, double tickBase, double tickIncr, boolean counterclockwise)
    Create a new instance of an axis.
    void
    setAxisScale(double scaleFactor)
    Set the axis scale.
    void
    setColor(Color color)
    Set the color of the axis.
    void
    Set the font parameters for this axis builder.
    void
    setLabelOffset(double offset)
    Set the offset for a label.
    void
    setLinearTickScaling(boolean mode)
    Set the tick-scaling mode Linear tick scaling causes getTickScaling(double) to return a constant value set by calling setTickScalingFactor(double).
    void
    Set whether or not tick labels are constrained to be horizontal.
    void
    setTickScalingFactor(double value)
    Set the tick-scaling factor.
    void
    setWidth(double width)
    Set the line width of an axis.
    boolean
    Determine whether or not tick labels are constrained to be horizontal.
    boolean
    Determine the tick-scaling mode.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • graph

      protected Graph graph
      The graph on which an axis will be drawn. Note: the axis must be drawn explicitly by calling Graph.draw(Graph.Axis). This is not done automatically because the caller might need to control the order in which various objects are drawn, including axes.
    • startX

      protected double startX
      The starting X position for the axis in graph coordinate space.
    • startY

      protected double startY
      The starting Y position for the axis in graph coordinate space.
    • length

      protected double length
      The length of the axis. This is never negative. The ending coordinates in graph coordinate space are never lower than the starting coordinates.
    • direction

      protected Graph.Axis.Dir direction
      The direction of the graph. The values of this field are either Graph.Axis.Dir.HORIZONTAL_INCREASING or Graph.Axis.Dir.VERTICAL_INCREASING.
    • counterclockwise

      protected boolean counterclockwise
      The orientation of the tick marks. If true, with the axis pointing from its start to its end in graph coordinate space the tick marks in graph coordinate space will lie in the counterclockwise direction. If false, the tick marks lie in the clockwise direction.
    • offset

      protected double offset
      The length in user space of the offset. The offset is the one in the direction that the tick marks point:
      • For tick marks pointing right, the lower X offset is used.
      • For tick marks pointing left, the upper X offset is used.
      • For tick marks pointing down, the lower Y offset is used.
      • For tick marks pointing up, the upper Y offset is used.
    • lower

      protected double lower
      The value of the graph's range that is closest to the left or lower edge of the graph (excluding offsets). The left edge is used for horizontal axes and the lower edge is used for vertical axes. The value is in graph coordinate space units.
    • upper

      protected double upper
      The value of the graph's range that is closest to the right or upper edge of the graph (excluding offsets). The right edge is used for horizontal axes and the upper edge is used for vertical axes. The value is in graph coordinate space units.
    • userLength

      protected double userLength
      The length of a graph in user space and in the direction of the axis, excluding the offsets. This is the maximum length of an axis if it is to fit in the graph's range.
    • stdLength

      protected double stdLength
      The length of the graph in graph coordinate space and in the direction of the axis, excluding the offsets. This is the maximum length of an axis if it is to fit in the graph's range.
    • label

      protected String label
      The label for an axis; null if there is no label.
    • labelSep

      protected double labelSep
      The separation from an axis label and the tick marks or tick-mark labels. The value is in user-space units. The default value is 5.0.
    • width

      protected double width
      The width of the axis. This is in user-space units.
    • color

      protected Color color
      The color for an axis. A null value implies that a default color will be used. This parameter controls the color of an axis and tick marks, not the color of labels (the color of labels is specified by a font parameter).
      See Also:
    • fontParms

      protected Graph.FontParms fontParms
      The fontParms for this axis. A null value implies that the graph's font parameters should be used.
    • tickLabelsHorizontal

      protected boolean tickLabelsHorizontal
      Indicate if tick labels are constrained to be horizontal. True if the labels must be horizontal; false otherwise. The default is true. If false vertical axes are affected but no horizontal axes.
    • axisScale

      protected double axisScale
      The axis scale.
      See Also:
    • levelLengths

      protected double[] levelLengths
      For each level, this array provides the number by which to multiple the axis width (in user-space units) to obtain the tick-mark length.
    • levelWidths

      protected double[] levelWidths
      For each level, this array provides the number by which to multiple the axis width (in user-space units) to obtain the tick-mark width.
    • labelSeps

      protected double[] labelSeps
      For each level, this number provides the separation in user-space units between tick labels and tick marks.
  • Constructor Details

    • AxisBuilder

      protected AxisBuilder(Graph g, double startX, double startY, double length, boolean horizontal, String label)
      Constructor.
      Parameters:
      g - the graph
      startX - the X value in graph coordinate space for the start of the axis.
      startY - the Y value in graph coordinate space for the start of the axis
      length - the length of the axis in graph coordinate space units
      horizontal - true if the axis is horizontal; false if it is vertical
      label - the level for an axis; null if none is provided
    • AxisBuilder

      protected AxisBuilder(Graph g, double startX, double startY, double length, boolean horizontal, boolean flip, String label)
      Constructor with a "flip" option. Normally the tick marks for an axis are below the axis for a horizontal axis and to the left of an axis for a vertical axis. An option to flip the tick marks and labels to the opposite side of the axis is provided by this constructor for cases where an axis appears at the top of a graph or at its right side.
      Parameters:
      g - the graph
      startX - the X value in graph coordinate space for the start of the axis.
      startY - the Y value in graph coordinate space for the start of the axis
      length - the length of the axis in graph coordinate space units
      horizontal - true if the axis is horizontal; false if it is vertical
      flip - true of the tick marks should be flipped to the opposite side of the axis; false to use the default side
      label - the level for an axis; null if none is provided
  • Method Details

    • setColor

      public void setColor(Color color)
      Set the color of the axis.
      Parameters:
      color - the color; null for the default
    • setFontParms

      public void setFontParms(Graph.FontParms parms)
      Set the font parameters for this axis builder. The font parameters will determine the font to use and the color of the text.
      Parameters:
      parms - the font parameters to copy
    • setTickLabelsHorizontal

      public void setTickLabelsHorizontal(boolean mode)
      Set whether or not tick labels are constrained to be horizontal. This mode has no effect unless an axis is vertical. The default is true.
      Parameters:
      mode - true if tick labels must be horizontal; false if they may be vertical
    • tickLabelsAreHorizontal

      public boolean tickLabelsAreHorizontal()
      Determine whether or not tick labels are constrained to be horizontal. This mode has no effect unless an axis is vertical.
      Returns:
      true if tick labels must be horizontal; false if they may be vertical
    • setAxisScale

      public void setAxisScale(double scaleFactor) throws IllegalArgumentException
      Set the axis scale. The axis value that Graph.Axis.axisValue(long) returns will be divided by this factor. It does not affect the value returned by Graph.Axis.axisCoord(long). The default value is 1.0.

      The scale factor can be used to change units. For example, if a graph was configured so that the X axis shows distances in meters, setting this factor to 103 will allow the axis to label tick marks in units of kilometers.

      The value that should be passed to methods such as AxisBuilder.Linear.setMaximumExponent(int) must be based on the value before this scaling factor is applied (e.g, the valuel when this scaling factor is 1.0).

      Parameters:
      scaleFactor - the scaleFactor
      Throws:
      IllegalArgumentException - if the scale factor is not a positive double-precision number
      See Also:
    • getAxisScale

      public double getAxisScale()
      Get the axis scale.
      Returns:
      the value for the axis scale
      See Also:
    • setWidth

      public void setWidth(double width)
      Set the line width of an axis.
      Parameters:
      width - the width in user space; 0.0 for the default
    • getLabelOffset

      public double getLabelOffset()
      Get the offset for a label. The offset is the separation between tick marks and any tick-mark labels and the label for the axis as a whole.
      Returns:
      the offset in user-space units
    • setLabelOffset

      public void setLabelOffset(double offset)
      Set the offset for a label. The offset is the separation between tick marks and any tick-mark labels and the label for the axis as a whole. The default value is 5.0.

      Note: with horizontal tick-mark labels and vertical axes, the position of the label is set conservatively so that the label cannot overlap a tick mark without regard to the length of the label or which tick marks it might overlap. In some cases, this can put the label too far to the side to be visually appealing. In such cases, one might prefer to change this value from the default, perhaps setting it to a negative value.

      Parameters:
      offset - the offset in user-space units
    • setTickScalingFactor

      public void setTickScalingFactor(double value)
      Set the tick-scaling factor. This factor is used when setLinearTickScaling(boolean) is called with an argument whose value is true. The default value is 1.0, indicating no additional scaling.

      Calling setLinearTickScaling(true) and this method is useful when one wants to scale the the tick-mark parameters for each level by a constant amount.

      Parameters:
      value - the tick-scaling factor; 0 for the default
    • getTickScalingFactor

      public double getTickScalingFactor()
      Get the tick-scaling factor.
      Returns:
      the tick-scaling factor
    • setLinearTickScaling

      public void setLinearTickScaling(boolean mode)
      Set the tick-scaling mode Linear tick scaling causes getTickScaling(double) to return a constant value set by calling setTickScalingFactor(double). Otherwise a non-linear function is used.
      Parameters:
      mode - true when tick scaling is linear; false otherwise
    • usesLinearTickScaling

      public boolean usesLinearTickScaling()
      Determine the tick-scaling mode.
      Returns:
      true if tick-scaling is linear; false otherwise
    • getTickScaling

      public double getTickScaling(double axisWidth)
      Get the scaling factor applied to tick-mark dimensions for a given axis width. This method is used by createAxis(). By default, the dimensions provided for tick marks for an axis are multiplied by the width of the axis to get the dimensions used. This is done so that users can easily enlarge a graph. When an axis builder is used, the user is generally not enlarging the graph, so a different choice is appropriate.

      The behavior of this method depends on the mode passed to setLinearTickScaling(boolean). When the argument to this method is true, a scaling factor is returned. This factor has a default value of 1.0. When the argument is false (the default), the scaling is nonlinear.

      Parameters:
      axisWidth - the axis width in user-space units
      Returns:
      the scaling factor
    • getNumberOfLevels

      public int getNumberOfLevels()
      Get the number of levels.
      Returns:
      the number of levels
    • configureLevels

      public void configureLevels(double[] lengths, double[] widths, double[] labelSeps)
      Configure levels. The levels are indices into the arrays provided as arguments. If an array is null, the default will be restored. When used, the index of the array will be a level. For the lengths and widths array, the values used will be an array element multiplied by the width of the axis.

      The levels should be ordered so lower levels correspond to ticks that are further apart. The default values are given by the following arrays:

      • double lengths[] = {10.0, 7.5, 5.0, 3.0, 1.5};
      • double widths[] = {1.2, 1.0, 0.8, 0.65, 0.5};
      • double labelSeps[] = {5.0, 4.0, 3.5, 3.0, 3.0};;
      Parameters:
      lengths - the scaling factors for tick lengths
      widths - the scaling factors for tick widths
      labelSeps - the label separations
    • newAxisInstance

      protected abstract T newAxisInstance(double startX, double startY, Graph.Axis.Dir direction, double length, double tickBase, double tickIncr, boolean counterclockwise)
      Create a new instance of an axis. This is called by implementations of createAxis() to create a new instance of an axis. This method is provided to reduce the necessity of reimplementing createAxis() in subclasses of (for example) AxisBuilder.Linear and AxisBuilder.Log that a user might write.

      Note: for AxisBuilder.Log, the tickBase argument for this method is ignored (the value is computed from the other parameters in this case).

      Parameters:
      startX - the x coordinate of the axis' starting point in graph coordinate space
      startY - the y coordinate of the axis' starting point in graph coordinate space
      direction - the direction of the graph
      length - the length of the axis in graph coordinate space
      tickBase - the starting coordinate along the axis for graph ticks, given in graph-coordinate space
      tickIncr - the increment between possible tick locations in graph coordinate space units
      counterclockwise - the angular direction to follow to reach a graph's labels and tick marks
      Returns:
      a new axis
    • createAxis

      public abstract T createAxis()
      Create an axis. Users may add additional tick marks if desired.
      Returns:
      the axis that was created with its tick marks added