- Enclosing class:
- AxisBuilder<T extends Graph.Axis>
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:
- 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.
- 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.
- 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.
- 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.
- a long providing the total time in days. This is the total time in hours, provided as a long, divided by 24.
"%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 anint
and the argumentspacing
is an enumeration whose type isAxisBuilder.Spacing
. This method specifies a sequence of tick marks at intervals determined by itsspacing
argument. - addTickSpec(level, spacing, format). The argument
level
is anint
and the argumentspacing
is an enumeration whose type isAxisBuilder.Spacing
. The argumentformat
is aString
specifying a format as described above. - addTickSpec(level, divisor). The argument
level
is anint
and the argumentdivisor
is also anint
. The methodsetNumberOfSteps(int)
must be called with an argumentn
, anddivisor
must dividen
(i.e,n
must be an integral multiple ofdivisor
where the multiple is a positive integer.) This method has no effect unless the minimum spacing is set toAxisBuilder.Spacing.SECONDS
.
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
will produce the following axis:... 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()); ...
-
Nested Class Summary
Nested classes/interfaces inherited from class org.bzdev.graphs.AxisBuilder
AxisBuilder.ClockTime, AxisBuilder.Linear, AxisBuilder.Log, AxisBuilder.Spacing
-
Field Summary
Fields inherited from class org.bzdev.graphs.AxisBuilder
axisScale, color, counterclockwise, direction, fontParms, graph, label, labelSep, labelSeps, length, levelLengths, levelWidths, lower, offset, startX, startY, stdLength, tickLabelsHorizontal, upper, userLength, width
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
addTickSpec
(int level, int divisor) Add a tick specification given a divisor.void
addTickSpec
(int level, AxisBuilder.Spacing spacing) Add a tick specification given a spacing.void
addTickSpec
(int level, AxisBuilder.Spacing spacing, String format) Add a tick specification given a spacing and format.Create an axis.double
Get the distance in graph coordinates space, parallel to this axis, corresponding to one second in time.protected Graph.Axis
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
setNumberOfSteps
(int n) Set the number of steps.void
setOneSecond
(double gcsSecond) Set the distance in graph coordinate space corresponding to one second in time.void
Set the minimum and maximum spacings for similar ticks.Methods inherited from class org.bzdev.graphs.AxisBuilder
configureLevels, getAxisScale, getLabelOffset, getNumberOfLevels, getTickScaling, getTickScalingFactor, setAxisScale, setColor, setFontParms, setLabelOffset, setLinearTickScaling, setTickLabelsHorizontal, setTickScalingFactor, setWidth, tickLabelsAreHorizontal, usesLinearTickScaling
-
Constructor Details
-
ClockTime
public ClockTime(Graph g, double startX, double startY, double length, boolean horizontal, String label) Constructor.- Parameters:
g
- the graphstartX
- 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 axislength
- the length of the axis in graph coordinate space unitshorizontal
- true if the axis is horizontal; false if it is verticallabel
- 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 graphstartX
- 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 axislength
- the length of the axis in graph coordinate space unitshorizontal
- true if the axis is horizontal; false if it is verticalflip
- true of the tick marks should be flipped to the opposite side of the axis; false to use the default sidelabel
- 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
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 spacingmax
- 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 notAxisBuilder.Spacing.SECONDS
, this parameter has no effect. To actually display ticks allowed by this method, useaddTickSpec(int,int)
;- Parameters:
n
- the number of steps.- See Also:
-
addTickSpec
Add a tick specification given a spacing.- Parameters:
level
- the tick level, where larger numbers indicated smaller or thinner ticksspacing
- the spacing between ticks for this sequence
-
addTickSpec
Add a tick specification given a spacing and format.- Parameters:
level
- the tick level, where larger numbers indicated smaller or thinner ticksspacing
- the spacing between ticks for this sequenceformat
- the format string for a tick label (see the class documentation forAxisBuilder.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 buildercab
, calling
will place ticks at a fifth of a second intervals.cab.setNumberOfSteps(10); cab.addTickSpec(level, 5);
- Parameters:
level
- the tick level, where larger numbers indicated smaller or thinner ticksdivisor
- 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 ofAxisBuilder.createAxis()
to create a new instance of an axis. This method is provided to reduce the necessity of reimplementingAxisBuilder.createAxis()
in subclasses of (for example)AxisBuilder.Linear
andAxisBuilder.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 classAxisBuilder<Graph.Axis>
- Parameters:
startX
- the x coordinate of the axis' starting point in graph coordinate spacestartY
- the y coordinate of the axis' starting point in graph coordinate spacedirection
- the direction of the graphlength
- the length of the axis in graph coordinate spacetickBase
- the starting coordinate along the axis for graph ticks, given in graph-coordinate spacetickIncr
- the increment between possible tick locations in graph coordinate space unitscounterclockwise
- the angular direction to follow to reach a graph's labels and tick marks- Returns:
- a new axis
-
createAxis
Description copied from class:AxisBuilder
Create an axis. Users may add additional tick marks if desired.- Specified by:
createAxis
in classAxisBuilder<Graph.Axis>
- Returns:
- the axis that was created with its tick marks added
-