Class Graph.Axis

java.lang.Object
org.bzdev.graphs.Graph.Axis
Direct Known Subclasses:
Graph.LogAxis
Enclosing class:
Graph

public static class Graph.Axis extends Object
Class to specify a graph axis. This class supports a linear axis. It's subclass, LogAxis, provides a logarithmic axis. Users may wish to add additional subclasses.

A graph axis has a starting point, which is either an instance of Point2D or two arguments giving the starting points X and Y coordinates,. In both cases, the coordinates are specified in graph coordinate space. There is also a direction, a Graph.Axis.Dir constant VERTICAL_INCREASING, VERTICAL_DECREASING, HORIZONTAL_DECREASING, and HORIZONTAL_INCREASING, and a length, again a distance in graph coordinate space. These are provided as arguments to a constructor. Tick marks, if specified, will be on the clockwise or counterclockwise side of the axis. The possible locations of tick marks are defined by arguments given to the constructor:

  • tickBase gives the x or y coordinate in graph coordinate space to begin counting possible tick locations. The choice between an x or y coordinate is determined by the direction of the axis.
  • tickIncr is the increment in graph coordinate space between possible tick locations. This is always a positive number: the direction of the axis determines the sign. The interpretation of this value is subclass specific. For this class, tick locations are linearly spaced and the tick increment is the spacing between potential tick-mark locations.
  • counterclockwise is a boolean field. When true, any tick marks are shown in the counterclockwise direction from a line pointing in the direction of the axis.
Starting from tickBase, one increments a counter, moving in graph coordinate space by tickIncr each time the counter is incremented by 1, until one reaches the start of the axis. At this point, ticks may be drawn as long as the tick will not be located past the end of the axis. How ticks are drawn is specified by instances of the class Graph.TickSpec. Multiple instances of Graph.TickSpec can be added to an axis. Some rules provided in the documentation for Graph.TickSpec indicate which one is chosen at a given value of the counter. Note that Graph.LogAxis handles ticks differently than this class handles them.

The tick marks themselves are specified by creating instances of the class Graph.TickSpec and using the method addTick(Graph.TickSpec) to add a tick-mark specification to the axis. At runtime, an appropriate tick-mark specification will be chosen for each tick mark.

In addition, an axis may have a label. The method setLabel(String) provides the text of the label and the method setLabelOffset(double) provides the separation between the label and an axis's tick marks (including any text labeling a tick mark). In addition, there are some methods for determining properties of an axis: its width, color, and the font parameters used for labels.

As an example, if an x axis goes from 20 to 50 in graph coordinate space, the initial X coordinate will be 20 and the length of the axis will be 30. Setting the tick increment to 1.0 will allow ticks to be drawn at X coordinates 20, 21, 22, ..., 49, 50. In this case the tick base should have the value 20. One can then arrange for a label to appear at every 10th tick, which will place tick-mark labels at 20, 30, 40, and 50. By constraint, if the axis went from 23 to 53, the initial X coordinate would be 23, and the length would still be 30. By putting the tick base value at 20, every 10th tick will still be at 30, 40, and 50, where tick-mark labels would still be printed. A label at 20 would not be printed because 20 is outside the range of values that can appear on the axis.

Subclasses may use the following methods:

  • initialIndex(). This returns the initial value of the index - the minimum index such that a call to axisCoord(initialIndex()) will be the coordinate (x or y depending on the direction) of a point on the axis.
  • axisValue(long index). This returns the position corresponding to an index. The value is the one used to print any label associated with a tick mark.
  • axisCoord(long index). This returns the position along an axis as a point in graph coordinate space and is used to determine where a tick will be drawn.
  • notDone(double coordinate). This returns true if is argument (a coordinate in graph coordinate space) is one that lies on the axis. It returns false if the point is off the axis. The implementation increments the index until notDone(axisCoord(index)) returns false at the beginning of a while loop.
For this class, axisCoord and axisValue return the same value. For the class Graph.LogAxis, different values are returned.
See Also:
  • Constructor Details

    • Axis

      public Axis(Point2D start, Graph.Axis.Dir dir, double length, double tickBase, double tickIncr, boolean counterclockwise)
      Constructor given a starting point.
      Parameters:
      start - the starting point in graph coordinate space
      dir - 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
    • Axis

      public Axis(double startX, double startY, Graph.Axis.Dir dir, double length, double tickBase, double tickIncr, boolean counterclockwise)
      Constructor given a starting point's x and y coordinates.
      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
      dir - 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
  • Method Details

    • 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 false.
      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
    • getDir

      public Graph.Axis.Dir getDir()
      Get the direction of an axis. The direction is defined in graph coordinate space.
      Returns:
      the direction
    • getStartX

      public double getStartX()
      Get the X-coordinate start location of the axis.
      Returns:
      the start point in graph coordinate space
    • getStartY

      public double getStartY()
      Get the Y-coordinate start location of the axis.
      Returns:
      the start point in graph coordinate space
    • getEndX

      public double getEndX()
      Get the X-coordinate end location of the axis.
      Returns:
      the end point in graph coordinate space
    • getEndY

      public double getEndY()
      Get the X-coordinate end location of the axis.
      Returns:
      the end point in graph coordinate space
    • isCounterClockwise

      public boolean isCounterClockwise()
      Determine the direction of tick marks.
      Returns:
      true of tick marks should point in a counter-clockwise direction; false otherwise
    • getTickBase

      protected double getTickBase()
      Get the tick base. The tick base is the value corresponding to a tick index of zero. The index for the first tick on the axis may be offset from this value. The value is intended to be used by the class defining it.
      Returns:
      the tick base
    • getTickIncr

      protected double getTickIncr()
      Get the tick increment. The tick increment determines the distance between ticks. For Graph.Axis, it is the distance in user-coordinate space between possible tick locations. The value is intended to be used by the class defining it.
      Returns:
      the tick increment
    • setLabelOffset

      public void setLabelOffset(double offset)
      Set the offset for the label of an axis. This is the spacing from the tick marks, including any labels for the tick marks.
      Parameters:
      offset - the offset in user-space units
    • getLabelOffset

      public double getLabelOffset()
      Get the offset for the label of an axis. This is the spacing from the tick marks, including any labels for the tick marks.
      Returns:
      the offset in user-space units
    • setColor

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

      public Color getColor()
      Get the color of the axis.
      Returns:
      the color of the axis
    • setWidth

      public void setWidth(double width)
      Set the width of the axis
      Parameters:
      width - the width in user-space units
    • getWidth

      public double getWidth()
      Get the width of the axis
      Returns:
      the width in user-space units
    • setLabel

      public void setLabel(String label)
      Set the label of the axis.
      Parameters:
      label - the label
    • getLabel

      public String getLabel()
      Get the label of an axis
      Returns:
      the label; null if there is none
    • setLimitModulus

      protected void setLimitModulus(long value)
      Set the limit modulus. Some subclasses (e.g., LogAxis) have ticks that are not uniformly spaced, and the tick can be suppressed if the index modulo the limit modulus is larger than a tick-specified limit. A value of zero indicates that the limit modulus is not used. The limit modulus is not used by this class directly, but rather by the Graph.TickSpec class.
      Parameters:
      value - the limit modulus.
    • getLimitModulus

      public long getLimitModulus()
      Get the limit modulus. Some subclasses (e.g., LogAxis) have ticks that are not uniformly spaced, and the tick can be suppressed if the index modulo the limit modulus is larger than a tick-specified limit. The usage for the limit modulus is determined by subclasses - this class merely keeps track of its value.
      Returns:
      the limit modulus; 0 if none is set or to be used
    • addTick

      public void addTick(Graph.TickSpec tickSpec)
      Add a tick specification to a list of tick specifications. Tick specifications are ordered based on the value of the mod argument passed to their constructors, with the highest mod values appearing first. At a given tick position, the first one for which the method showTick returns true will be used.
      Parameters:
      tickSpec - the tick specification to add
    • setFontParms

      public void setFontParms(Graph.FontParms parms)
      Set the font parameters for the axis.
      Parameters:
      parms - the font parameters
    • getFontParms

      public Graph.FontParms getFontParms()
      Get the font parameters for an axis If there are none, the font parameters for the graph itself will be used. A non-null returned value will be a copy of the current font parameters for this axis.
      Returns:
      the font parameters; null if none are specified
    • initialIndex

      public long initialIndex()
      Get the initial index. This is the index for the first tick that can be displayed.
      Returns:
      the initial index
    • modifyGraphics

      public void modifyGraphics(Graphics2D g2d, long ind, Point2D p, Graph g, Line2D tickmark)
      Modify a graphics context. This method is called when the tick marks of an axis are about to be drawn. It enables the graphics context to be modified when the index reaches particular values. The index will increase sequentially from an initial value until the end of the axis is reached, but this method will be called only when there is a tick mark to draw.

      The tick mark is a Line2D that is drawn as a line segment with an appropriately configured stroke.

      A typical use might be to change the color of a tick mark or to place a small icon below a tick mark if the label was suppressed. The default implementation just returns.

      Parameters:
      g2d - the graphics context
      ind - the tick index
      p - the point on the axis corresponding to the tick index and expressed in user-space units
      g - the graph
      tickmark - the tick mark
    • restoreGraphics

      public void restoreGraphics(Graphics2D g2d)
      Restore a graphics context. Subclasses that override modifyGraphics must implement this method so that it restores the graphics context to the state it was in just before the previous call to modifyGraphics.
      Parameters:
      g2d - the graphics context to restore.
    • modifyFontParms

      public void modifyFontParms(Graph.FontParms fp, long ind, Point2D p, Graph g)
      Modify font parameters. This method is called when the tick marks of an axis are about to be drawn. It enables the font parameters to be modified when the index reaches particular values. The index will increase sequentially from an initial value until the end of the axis is reached, but this method will be called only when there is a tick mark to draw. It will have an effect on any tick-mark label that is drawn.

      When a tick mark's label is drawn, a different graphics context is used. The argument fp can, however, be modified in various ways: to change the font color or perhaps the label's orientation.

      Parameters:
      fp - the font parameters
      ind - the tick index
      p - the point on the axis corresponding to the tick index and expressed in user-space units
      g - the graph
    • restoreFontParms

      public void restoreFontParms(Graph.FontParms fp)
      Restore font parameters to what they were before the previous call to modifyFontParms. Subclasses must implement this method if modifyFontParms is implemented.
      Parameters:
      fp - the font parameters to be restored
    • setAxisScale

      public void setAxisScale(double scaleFactor) throws IllegalArgumentException
      Set the axis scale. The axis value that axisValue(long) returns will be divided by this factor. It does not affect the value returned by 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.

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

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

      public double axisValue(long ind)
      Get the value for a point on an axis for which there may be a tick. The value is the one used to print a label for ticks that label their coordinates.
      Parameters:
      ind - the index
      Returns:
      the value corresponding to the index
    • axisCoord

      public double axisCoord(long ind)
      Get the coordinate value for a point on an axis for which there may be a tick. This will determine the x or y coordinate at which a tick mark may appear.
      Parameters:
      ind - the index
      Returns:
      the value in graph coordinate space corresponding to the index
    • notDone

      public boolean notDone(double sc)
      Determine if iteration over ticks is not complete. This is called at the start the loop in a 'while' statement.
      Parameters:
      sc - the current location in graph coordinate space
      Returns:
      true if iteration should continue; false otherwise