Class Graph.TickSpec

java.lang.Object
org.bzdev.graphs.Graph.TickSpec
All Implemented Interfaces:
Comparable<Graph.TickSpec>
Enclosing class:
Graph

public static class Graph.TickSpec extends Object implements Comparable<Graph.TickSpec>
Class specifying graph tick marks along an axis. Instances of this class are used by Graph.Axis to determine whether a tick at an index (see Graph.Axis) is printed and if printed, how it is printed. Ticks are characterized by several parameters:
  • length. The length is a scaling factor that is multiplied by an axis width to obtain the length of a tick mark in user space.
  • width. The width is a scaling factor that is multiplied by an axis width to obtain the width of a tick mark in user space.
  • mod. This is the modulus for a tick mark and is a positive integer. The value index%mod is used in tests described below.
  • modtest. This value is a non-negative integer. For a given index supplied by a caller, a necessary condition for a tick mark to be shown is that (index % mod) == modtest.
  • limit. When 0, this field is ignored. It is also ignored if the limit modulus of the Graph.Axis is zero. Otherwise limit is a positive integer and a necessary condition for a tick mark to be shown is that ((index % mod) % limitModulus ≤ limit. The limit modulus is set to zero for instances of Graph.Axis and to a nonzero value for instances of Graph.LogAxis. For a logarithmic axis, a limit allows closely-spaced ticks to be used near the start of a decade but suppressed near its end where tick marks tend to "bunch up".
  • format. A format provides the format for a tick-specific label. This is used by the method getTickLabel(double,double,Graph.Axis,long) to format a double-precision value using an instance of SciFormatter to format the value.
  • stringOffset. The offset in user-space units between a tick mark and a string labeling the tick mark.
To label ticks SciFormatter is used (although the method that creates the label can be overridden). This formatter is similar to java.util.Formatter, but can print numbers using scientific notation by using Unicode to provide multiplication signs and superscripts.

When multiple TickSpec instances are added to an axis, they are sorted on the basis of the modulus, length, width, modtest, string offset, and existence of a format (in that order with the first that does not produce a tie determining the comparison. The order is determined by

  • the modulus.
  • the length for tied values of the modulus.
  • the width for tied values of the length and modulus.
  • the modtest value for tied values of the width, etc.
  • the string offset for tied values of the modtest, etc.
  • the presence of a format for tied values of the string offset, etc.
While the TickSpec class determines the ordering the class Graph.Axis sorts its instances of TickSpec into the appropriate order and selects the best one to use.

For a linear axis, one will typically use a construct whose arguments provide a tick length, tick width, and a modulus, with optionally a format and string offset. For an axis going from 20 to 50, with a tick increment of 1, one might use three instances of TickSpec:

  • new Graph.TickSpec(3.0, 1.0, 1)
  • new Graph.TickSpec(5.0, 2.0, 5)
  • new Graph.TickSpec(5.0, 2.0, 10, "%2.0F", 5.0)
This will produce ticks of various lengths, with the most 3.0 units long. Tick marks at 25, 35, and 45 will be 5 units long and twice as wide. The tick marks at 20, 30, 40, and 50 will additionally have a label providing the coordinate.

For a logarithmic axis going from 1.0 to 100.0 (0 to 2 in graph coordinate space) with a tick increment of 1.0, one might use the following tick specifications:

  • new Graph.TickSpec(10.0, 1.0, 9, "%3.0f", 5.0). This will create ticks with labels at x values of 1.0, 10.0, and 100.0 (graph-coordinate-space values are 0.0, 1.0, and 2.0 respectively).
  • new Graph.TickSpec(5.0, 1.0, 9, 4). This will create ticks at 5.0 and 50.0 (graph-coordinate-space values are log10(5) and log10(50) respectively).
  • new Graph.TickSpec(3.0, 0.5, 1). This will create tick marks at 2, 3, 4, 5, 6, 7, 8, 9, 20, 30, 40, 50, 60, 70, 80, and 90. It will also specify tick marks at 1, 10, and 100 but the first specification will be chosen due to the search order so the tick marks at 1, 10, and 100 will be ignored for this tick specification.

Subclasses may be written to handle additional cases. These can use the methods

All of these three methods take the same arguments:
  • the numerical value to be printed.
  • the coordinate (X or Y depending on the direction of the axis) in graph coordinate space where the tick mark should be printed.
  • the axis.
  • the index.
To implement a bar chart, for example, one could space the ticks appropriately and override getTickLabel(double,double,Graph.Axis,long) so that it returns an appropriate string based on the index. The default implementation for these methods is appropriate for linear and logarithmic axes.
  • Constructor Summary

    Constructors
    Constructor
    Description
    TickSpec(double length, double width, int mod)
    Constructor.
    TickSpec(double length, double width, int mod, int modtest)
    Constructor with modulus test.
    TickSpec(double length, double width, int mod, int modtest, int limit)
    Constructor with limit and modulus test.
    TickSpec(double length, double width, int mod, int modtest, int limit, String format, double stringOffset)
    Constructor with format, modulus test, and limit.
    TickSpec(double length, double width, int mod, int modtest, String format, double stringOffset)
    Constructor with format and modulus test.
    TickSpec(double length, double width, int mod, String format, double stringOffset)
    Constructor with format.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
     
    boolean
     
    Get the format string.
    getTickLabel(double s, double sc, Graph.Axis axis, long ind)
    Get the format string for a tick mark.
    boolean
    showTick(double s, double sc, Graph.Axis axis, long ind)
    Determine if a tick mark should be shown.
    boolean
    showTickLabel(double s, double sc, Graph.Axis axis, long ind)
    Determine if a label should be printed.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • TickSpec

      public TickSpec(double length, double width, int mod)
      Constructor.
      Parameters:
      length - the length of a tick mark in multiples of the axis width, which is in user-space units
      width - the width of a tick mark in multiples of the axis width, which is in user-space units
      mod - the modulus for determining when tick marks are shown
    • TickSpec

      public TickSpec(double length, double width, int mod, int modtest)
      Constructor with modulus test.
      Parameters:
      length - the length of a tick mark in multiples of the axis width, which is in user-space units
      width - the width of a tick mark in multiples of the axis width, which is in user-space units
      mod - the modulus for determining when tick marks are shown
      modtest - the modulus test
    • TickSpec

      public TickSpec(double length, double width, int mod, int modtest, int limit)
      Constructor with limit and modulus test.
      Parameters:
      length - the length of a tick mark in multiples of the axis width, which is in user-space units
      width - the width of a tick mark in multiples of the axis width, which is in user-space units
      mod - the modulus for determining when tick marks are shown
      modtest - the modulus test
      limit - the maximum value of the index (mod limitModulus); -1 if the limit should be ignored
    • TickSpec

      public TickSpec(double length, double width, int mod, String format, double stringOffset)
      Constructor with format.
      Parameters:
      length - the length of a tick mark in multiples of the axis width, which is in user-space units
      width - the width of a tick mark in multiples of the axis width, which is in user-space units
      mod - the modulus for determining when tick marks are shown
      format - the printf format used to determine the label string for an argument of type double; null if there is none
      stringOffset - the distance in user space between a tick mark and a label
    • TickSpec

      public TickSpec(double length, double width, int mod, int modtest, String format, double stringOffset)
      Constructor with format and modulus test.
      Parameters:
      length - the length of a tick mark in multiples of the axis width, which is in user-space units
      width - the width of a tick mark in multiples of the axis width, which is in user-space units
      mod - the modulus for determining when tick marks are shown
      modtest - the modulus test
      format - the printf format used to determine the label string for an argument of type double; null if there is none
      stringOffset - the distance in user space between a tick mark and a label
    • TickSpec

      public TickSpec(double length, double width, int mod, int modtest, int limit, String format, double stringOffset)
      Constructor with format, modulus test, and limit.
      Parameters:
      length - the length of a tick mark in multiples of the axis width, which is in user-space units
      width - the width of a tick mark in multiples of the axis width, which is in user-space units
      mod - the modulus for determining when tick marks are shown
      modtest - the modulus test
      limit - the maximum value of the index (mod limitModulus); -1 if the limit should be ignored
      format - the printf format used to determine the label string for an argument of type double; null if there is none
      stringOffset - the distance in user space between a tick mark and a tick label
  • Method Details

    • compareTo

      public int compareTo(Graph.TickSpec other)
      Specified by:
      compareTo in interface Comparable<Graph.TickSpec>
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • getFormat

      public String getFormat()
      Get the format string.
      Returns:
      the format string provided by a constructor; null if there is none
    • showTick

      public boolean showTick(double s, double sc, Graph.Axis axis, long ind) throws UnsupportedOperationException
      Determine if a tick mark should be shown. The default implementation computes (ind % mod), where mod is a parameter given to the constructor, and allows a tick mark when (ind % mod) is equal to the value of the modtest argument provided by a constructor (the default for modtest is zero). If a positive limit modulus (limitModulus) was provided with a non-negative limit, ((ind % mod) % limitModulus) must be less than or equal to limit. For example, for a logarithmic axis, a limit allows a higher density of ticks to be used at the start of a decade, but not near its end, where the tick marks tend to "bunch up".
      Parameters:
      s - the numerical value to be printed
      sc - the location along the axis in graph coordinate space
      axis - the axis
      ind - the index (the number of tick locations before the current one)
      Returns:
      true if a tick should be displayed; false otherwise
      Throws:
      UnsupportedOperationException
    • showTickLabel

      public boolean showTickLabel(double s, double sc, Graph.Axis axis, long ind)
      Determine if a label should be printed. This method is only called if showTick with the same arguments returns true. The default implementation checks that the format field (set by a constructor) is not null and if that is the case, returns true; false otherwise.
      Parameters:
      s - the numerical value to be printed
      sc - the location along the axis in graph coordinate space
      axis - the axis
      ind - the index (the number of tick locations before the current one)
      Returns:
      true if a string should be displayed; false otherwise
    • getTickLabel

      public String getTickLabel(double s, double sc, Graph.Axis axis, long ind)
      Get the format string for a tick mark. This method is only called if showTickLabel, when called with the same arguments, returns true. The default implementation simply returns a string representation of s using the format passed to some of the constructors. The formatting is done using SciFormatter. This can be overridden if different tick marks require different formats.
      Parameters:
      s - the numerical value to be printed
      sc - the location along the axis in graph coordinate space
      axis - the axis for this label
      ind - the index (the number of tick locations before the current one)
      Returns:
      the formatted string; null if there is none