Class AxisBuilder.ClockTime

java.lang.Object
org.bzdev.graphs.AxisBuilder<Graph.Axis>
org.bzdev.graphs.AxisBuilder.ClockTime
Enclosing class:
AxisBuilder<T extends Graph.Axis>

public static class AxisBuilder.ClockTime extends AxisBuilder<Graph.Axis>
AxisBuilder for axes that use a combination of hours, minutes, and seconds. An axis will space tick marks so that hours are divided into 60 minutes and minutes are divided into 60 seconds. The distance is graph coordinate space corresponding to 1 second is set by calling setOneSecond(double) (the default GCS distance is 1.0).

Ticks are characterized by a spacing and a level. The spacings for this class are described by an enumeration type AxisBuilder.Spacing. In addition, ticks spaced at one-second intervals can be subdivided into a number of steps with ticks at selective locations (the spacing between visible ticks must be a divisor of the number of steps - if the number of steps is 10, the visible ticks can be at the midpoint, at every other step, or at all steps, with the divisors being 2, 5, or 10 respectively). The levels determine the length and width of tick marks. Higher levels correspond to smaller or narrower tick marks.

Ticks that can be labeled are integral multiples of one second, and have their format described by a format string. This format string can process up to four arguments:

  1. An instance of java.util.Calendar. The time actually provided in UTC time (or POSIX time), starting at 00:00:00, Thursday, 1 January 1970. The day, day of the week, and year should be ignored. Formatting directives will print the minute, hour, and second components: the minutes and seconds are given modulo 60 and the hours are given modulo 12 or 24. The directives for these hours, minutes, and seconds fields are %1$TH, %1$TM, and %1$TS respectively. In each case, the field will be two characters long, possibly with leading zeros.
  2. a long providing the total time in hours. This is the total time in minutes, provided as a long, divided by 60L. A useful formatting directive for this value is %2$02d. This provides two-character fields with leading zeros, with more characters added for larger values.
  3. a long providing the total time in minutes. This is the total time in seconds, provided as a long, divided by 60L. A useful formatting directive for this value is %3$02d. This provides two-character fields with leading zeros, with more characters added for larger values.
  4. a long providing the total time in seconds. This is the double-precision time in seconds rounded to the nearest integer value (only integral values are used when printing tick labels, so the rounding eliminates floating-point errors). A useful formatting directive for this value is %4$02d. This provides two-character fields with leading zeros, with more characters added for larger values.
  5. a long providing the total time in days. This is the total time in hours, provided as a long, divided by 24.
For example, the format string "%3$02d:00" could be used for tick-marks spaced at minute intervals, with values at or above 60 printed as is. By contrast, "%1$TT" will print the time for each tick mark as hours, minutes, and seconds, each two characters long and separated by colons (The Java API documentation states that "%1$TT" is equivalent to "%1$TH:%1$TM:$1$TS"). In this case, the minutes field will have values from 0 to 59.

After a constructor is called (its arguments are same as for AxisBuilder.Linear), the user should call setSpacings(AxisBuilder.Spacing,AxisBuilder.Spacing) to set the minimum and maximum spacings. Excluding tick spacings set by using a divisor (see below), the minimum and maximum spacings are the smallest and largest spacings used for sequences of ticks. When two sequences result in a tick at the same location on an axis, ordering rules pick the one that will be shown. Generally, longer ticks and ticks with tick labels are preferred. Tick marks and tick labels are added by using the following methods:

  • addTickSpec(level, spacing). The argument level is an int and the argument spacing is an enumeration whose type is AxisBuilder.Spacing. This method specifies a sequence of tick marks at intervals determined by its spacing argument.
  • addTickSpec(level, spacing, format). The argument level is an int and the argument spacing is an enumeration whose type is AxisBuilder.Spacing. The argument format is a String specifying a format as described above.
  • addTickSpec(level, divisor). The argument level is an int and the argument divisor is also an int. The method setNumberOfSteps(int) must be called with an argument n, and divisor must divide n (i.e, n must be an integral multiple of divisor where the multiple is a positive integer.) This method has no effect unless the minimum spacing is set to AxisBuilder.Spacing.SECONDS.
Finally, AxisBuilder.createAxis() will be called to create an axis. The method AxisBuilder.setAxisScale(double) should be used cautiously if at all: it was designed for cases where units change by factors of 10 (or some other factor), not cases in which the units are mixed.

As an example, the following code


  ...
  AxisBuilder.ClockTime ab;
  ab = new AxisBuilder.ClockTime(graph,
                                 0.0, 0.0,
                                 MKS.hours(2.0),
                                 true,
                                 null);

  ab.setSpacings(AxisBuilder.Spacing.SECONDS,
                 AxisBuilder.Spacing.HOURS);

  ab.addTickSpec(0, AxisBuilder.Spacing.HOURS, "%1$TR" );
  ab.addTickSpec(1, AxisBuilder.Spacing.THIRTY_MINUTES,
                 "%1$TR" );
  ab.addTickSpec(1, AxisBuilder.Spacing.TEN_MINUTES, null);
  ab.addTickSpec(2, AxisBuilder.Spacing.MINUTES, null);
  graph.draw(ab.createAxis());
  ...
 
will produce the following axis:

clock-time axis example

  • Constructor Details

    • ClockTime

      public ClockTime(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
    • ClockTime

      public ClockTime(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

    • setOneSecond

      public void setOneSecond(double gcsSecond)
      Set the distance in graph coordinate space corresponding to one second in time.
      Parameters:
      gcsSecond - the distance in graph coordinate space, parallel to this axis, that corresponds to one second.
    • getOneSecond

      public double getOneSecond()
      Get the distance in graph coordinates space, parallel to this axis, corresponding to one second in time.
      Returns:
      the distance in graph coordinate space representing one second in time.
    • setSpacings

      public void setSpacings(AxisBuilder.Spacing min, AxisBuilder.Spacing max)
      Set the minimum and maximum spacings for similar ticks. Set the minimum and maximum spacing for sequences of ticks that may have a label.

      The minimum spacing should be the largest minimum for which ticks will be shown, excluding sub-second tick spacings: making the value smaller reduces performance. The value will typically be equal to the closest-spaced sequence of ticks whose spacing is at least one second.

      The maximum spacing determines the point from which a sequence of possible tick locations will be generated. This value should be as small as possible. The value will typically be the spacing between the longest tick marks.

      In both cases, the values are determined by an enumeration type. Legal values of AxisBuilder.Spacing for the minimum spacing are SECONDS, MINUTES, and HOURS. For the maximum spacing, the legal values are SECONDS, MINUTES, HOURS, and DAYS. The minimum must not represent a longer time interval than the maximum.

      Parameters:
      min - the minimum spacing
      max - the maximum spacing.
    • setNumberOfSteps

      public void setNumberOfSteps(int n)
      Set the number of steps. The number of steps is the number of subdivisions of one second at which ticks may appear. The tick increment will then be getOneSecond()/n. The default number is 1. Higher values are useful when an interval should be divided into subintervals other than 10. For example, setting the number of steps to 4 will allow one to create ticks that divide one second into quarters. If the value is 1, or the minimum spacing is not AxisBuilder.Spacing.SECONDS, this parameter has no effect. To actually display ticks allowed by this method, use addTickSpec(int,int);
      Parameters:
      n - the number of steps.
      See Also:
    • addTickSpec

      public void addTickSpec(int level, AxisBuilder.Spacing spacing)
      Add a tick specification given a spacing.
      Parameters:
      level - the tick level, where larger numbers indicated smaller or thinner ticks
      spacing - the spacing between ticks for this sequence
    • addTickSpec

      public void addTickSpec(int level, AxisBuilder.Spacing spacing, String format)
      Add a tick specification given a spacing and format.
      Parameters:
      level - the tick level, where larger numbers indicated smaller or thinner ticks
      spacing - the spacing between ticks for this sequence
      format - the format string for a tick label (see the class documentation for AxisBuilder.ClockTime).
    • addTickSpec

      public void addTickSpec(int level, int divisor)
      Add a tick specification given a divisor. The divisor indicates the number of intervals separating ticks. For example, for an axis builder cab, calling
      
             cab.setNumberOfSteps(10);
             cab.addTickSpec(level, 5);
       
      will place ticks at a fifth of a second intervals.
      Parameters:
      level - the tick level, where larger numbers indicated smaller or thinner ticks
      divisor - a divisor of the number of steps, indicating the number of spaces that will separate ticks over a one-second interval.
    • newAxisInstance

      protected Graph.Axis newAxisInstance(double startX, double startY, Graph.Axis.Dir direction, double length, double tickBase, double tickIncr, boolean counterclockwise)
      Description copied from class: AxisBuilder
      Create a new instance of an axis. This is called by implementations of AxisBuilder.createAxis() to create a new instance of an axis. This method is provided to reduce the necessity of reimplementing AxisBuilder.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).

      Specified by:
      newAxisInstance in class AxisBuilder<Graph.Axis>
      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 Graph.Axis createAxis()
      Description copied from class: AxisBuilder
      Create an axis. Users may add additional tick marks if desired.
      Specified by:
      createAxis in class AxisBuilder<Graph.Axis>
      Returns:
      the axis that was created with its tick marks added