Axis Parameters

Most NetCharts applets support the definition and display of one or more axes, depending on the specific chart type. Currently, the following standard axes are defined for most charts:

Generally, the Bottom and Left axes are used by default to map the X and Y data values, although in the TimeChart, for example, the Top axis is a more natural default axis.

For each of the axes, the following parameters can be used to specify various display characteristics for that axis:

TopAxis Specifies most axis attributes.
TopColor Specifies axis and tic mark color.
TopTics Specifies tic mark label font attributes.
TopScale Specifies tic mark locations and visible range of axis values.
TopScroll Specifies scrollable range of axis.
TopFormat Specifies tic mark label format.
TopLabels Specifies custom tic mark labels.
TopActiveLabels Specifies active labels to be associated with the axis tic labels.

where "Top" can be replaced by "Bottom", "Left" or "Right". (Throughout the following discussion, the TopAxis will be referenced, but all topics and parameters apply to all axes in a chart.)

All Axis Attributes

	TopAxis = (TicColor, "TicFont", TicFontSize, TicFontAngle,
	           MinValue, MaxValue, StepValue,
	           AxisColor,
	           ScrollMin, ScrollMax);

The TopAxis parameter is provided to allow the specification of all attributes for a given axis, except for the optional axis labels and the tic mark label format. The TopAxis parameter is processed prior to the other parameters. As such, it can be used to set the initial or default values for an axis, which will overridden by any attribute settings made using the other axis parameters, either in the same parameter script or when dynamically updating parameters.

NOTE: The TopAxis and BottomAxis parameters have a custom definition in the Strip Chart. See NFStripChartApp for more details.

Axis Color

	TopColor = AxisColor;

The TopColor parameter is used to specify the color of the axis and the tic marks, but not the tic mark labels. The default axis color is black. If the "null" color is specified, the axis color is not changed by this parameter.

Tic Mark Label Attributes

	TopTics = ("Mode", Color, "Font", FontSize, FontAngle);

The TopTics parameter specifies the label attributes for the tic marks displayed along the axis. If TicMode is "OFF", then the tic marks will not be displayed, otherwise the tic labels will be generated based on the other parameter settings and will be displayed using the given label attributes in the TopTics parameter. If any attribute is not defined, the previous value of that attribute will be used. See Label Parameters for more details concerning label attributes.

Tic Mark Locations

	TopScale = (MinValue, MaxValue, StepValue);

The TopScale parameter specifies the min and max data values to be displayed along the axis. If the TopScale parameter is not defined or the MinValue and MaxValue parameters are the same or one of them is not defined, then the tic mark locations will be automatically determined based on the actual data values being displayed. That is, the axis will be "autoscaled" using the current data values to determine "reasonable" values for MinValue, MaxValue and StepValue.

The StepValue is optional and may be used to specify a given step between tic marks along the axis, starting with the MinValue. If the StepValue is not an even multiple of the difference between the MinValue and MaxValue, then no tic mark will be displayed at the MaxValue. If StepValue is not defined, tic marks will be placed at "reasonable" locations along the axis, depending on the range of values being displayed.

NOTE, in some charts, the TopScale parameter is ignored for a given axis. For example, in the BarChart, the BottomScale attributes are automatically determined by the number of bars being displayed.

NOTE, the TopScale and BottomScale parameters are not supported in Strip Charts.

Tic Mark Label Format

	TopFormat = (FormatType, "FormatExpr", "TimeBase", "TimeUnit");

The numeric labels that are automatically generated by the axis can be formatted using the TopFormat parameter. The FormatType attribute specifies the type of number being displayed by that axis, with the following types currently supported:

The FLOAT type specifies that the numeric values should be displayed with decimal parts, while the INTEGER type specifies that the numeric values should be displayed as integers, rounded if necessary. The DATE type specifies that the axis tic values should be interpreted as date/time values. See
Date/Time Values for more details concerning date and time values.

The FormatExpr attribute of the TopFormat parameter specifies a display format to be used for each axis tic label and each active label displayed generated by default. The format allows a developer to specify numeric and date/time formats using expressions similar to those provided in the C/Unix printf function. The format expressions can consist of an arbitrary string, plus one or more occurences of format components, which are preceded by '%'.

The TimeBase and TimeUnit attributes are used only for the DATE format type. The TimeBase attribute specifies the base date to be used when determining the actual date/time value when a time unit or numeric value is used in the TopScale, TopScroll or DataSet parameters. The TimeUnit attribute specifies the time unit multiplier to be used when determining the actual data/time value when a numeric value is used in the TopScale, TopScroll or DataSet parameters. See Date/Time Values for more details concerning date and time values.

Numeric Formats

The following format components are supported for the numeric format types:

Format Type Component(s) Description
FLOAT %f Display numeric value with fixed number of decimal digits, possibly zero.
%g Display numeric value using platform specific default format. Generally, this results in a "reasonable" format, unless a large number of decimal digits exists or the number is very large or very small.
INTEGER %d Display numeric value as an integer, rounding if necessary.

For the numeric types, the following modifier can be applied to the format component to yield different outputs:

	-0WW.DD
where all parts are optional and are interpreted as follows:

- Left justify the result, otherwise right justify it.
0 Pad with leading zeros, if necessary, to fill entire field.
WW Total width of the formatted field. If the field is naturally wider than this value, it is ignored.
DD Number of decimal digits to display (%f format only). If not specified, the default number is 2.

For example, for the FLOAT value 123.456, the following formats yield the result shown:

Format Result
%g 123.456
%f 123.46
%d 123
%8.1f 123.5
%08.1f 000123.5
Cost = $%.1fM Cost = $123.5M

Date/Time Formats

The following formats are supported for the DATE format type:

%L standard Java locale format ('Mon Jan 01 00:00:00 1996')
%G standard Java GMT format ('1 Jan 1996 00:00:00 GMT')
%Y year as YYYY (1900+)
%y year as YY (00-99)
%M month as MM (01-12)
%N long month name ("January", "February", ...)
%n short month name ("Jan", "Feb", ...)
%W long weekday name ("Sunday", "Monday", ...)
%w short weekday name ("Sun", "Mon", ...)
%d day of month as DD (01-31)
%h hour as HH (00-23)
%m minute as MM (00-59)
%s second as SS (00-59)

For example, for the DATE value '10 April 1996 12:37', the following formats yield the result shown:

Format Result
%L Wed Apr 10 12:37:00 1996
%M/%d/%Y\n%h:%m:%s 04/10/1996
12:37:00
%N %d, %Y April 10, 1996

Tic Mark Labels

	TopLabels = "Label1", "Label2", ...;

The TopLabels parameter specifies a list of custom tic mark labels, that will be used instead of the numeric labels automatically generated by the axis. The TopLabels will be evenly placed along the axis, overriding any tic placement specified by the StepValue attribute.

In a Bar/Combo/Stock Chart, the BarLabels parameter overrides the BottomLabels (for VERTICAL bars) or the LeftLabels (for HORIZONTAL bars) parameters.

Tic Mark Active Labels

	TopActiveLabels = ("Label1", "URL1", "Target1"),
	                  ("Label2", "URL2", "Target2"),
	                  ...;

The TopActiveLabels parameter specifies a list of custom active labels to be associated with each tic mark label. That is, these labels will be displayed whenever the mouse "dwells" over a given tic mark label. This can be used to provide the user with additional information about that particular value or to "drill-down" to another document. See Active Labels for a detailed explanation of active label capabilities.

In a Bar/Combo/Stock Chart, the BarActiveLabels parameter overrides the BottomActiveLabels (for VERTICAL bars) or the LeftActiveLabels (for HORIZONTAL bars) parameters.

Axis Scrolling/Zooming

	TopScroll = (ScrollMin, ScrollMax);

The TopScroll parameter specifies a range of values in which the axis can be scrolled. When the ScrollMin and ScrollMax values are defined for a given axis, the axis will be displayed as a slider bar, using the axis color defined, with a white background. The relative size of the slider represents the percentage of the entire range currently being displayed. That is, it graphically depicts the size of the current axis range (MinValue and MaxValue attributes) relative to the scrollable region (ScrollMin and ScrollMax attributes).

Both values must be set in order for axis scrolling/zooming to be enabled and they should be smaller and larger than the Min and Max attributes specified for the same axis.

When scrolling is enabled for one or more axes, the following user interaction is supported:

  1. If the user drags the slider along the axis, the current min/max values for the axis will be updated accordingly and the chart will be redrawn using those new values when the mouse button is released.
  2. If the user clicks on either side of the slider, in the white area, the slider will "step" in that direction by one tick mark and the chart will be redrawn.
  3. If the user clicks within the slider bar itself while the SHIFT key is held down, then the axis will zoom IN by a factor of 2. (i.e., the axis range will be cut in half).
  4. If the user clicks within the slider bar itself while the CONTROL key is held down, then the axis will zoom OUT by a factor of 2. (i.e., the axis range will be doubled).
  5. If the user clicks anywhere within the CHART, while holding either the SHIFT or CONTROL key down, then ALL axes will be zoomed accordingly. This allows both the X and Y axes to be halved or doubled at the same time.

NOTE, the TopScale and BottomScale parameters are not supported in Strip Charts.

Examples

This example shows an XY chart with default left and bottom axes:

This example shows an XY chart, with the following axis parameters specified:

LeftScale   = (-1.50, 5.00);

BottomScale = (0, 100, 20);

This example shows an XY chart, with the following axis parameters specified:

LeftColor    = cyan;
LeftTics     = ("ON", red, "Courier");
LeftScale    = (-1, 5, 1.5);
LeftFormat   = (FLOAT, "%.1f");

BottomColor  = magenta;
BottomTics   = ("ON", green, "TimesRoman");
BottomScale  = (0, 100, 20);
BottomFormat = (INTEGER, "X=%d");

This example shows an XY chart, with the BottomLabels parameter used to define three custom tic labels

LeftScale    = (-1, 5, 1.5);

BottomScale  = (0, 100, 20);
BottomLabels = "Min\nValue", "Middle\nValue", "Max\nValue";

In this example, a TimeChart is defined with custom date/time label format and a scrollable top axis.

TopFormat  = (DATE, "%M/%D", "1 Apr 96", "1d");
TopTics	   = ("ON", black, "TimesRoman", 14);
TopScale   = ("1 Apr 96", "1 Jun 96", "7d");
TopScroll  = (0, 90);

LeftFormat = (FLOAT, "%.2f");
LeftAxis   = (black, "TimesRoman", 16, 0);
Note, the TimeBase and TimeUnit attributes are defined in the TopFormat to specify the base and unit values to be used when interpreting any numeric values given in the DataSet parameters or in the TopScroll parameter. Furthermore, the MinValue and MaxValue attributes in the TopScale parameter are defined using absolute date values, while the StepValue is defined using a time unit value (7 days). See
Date/Time Values for more details about date/time values.

Click on the black bar in the top axis and drag it to scroll the time axis. Click anywhere in the chart while the SHIFT key is depressed to zoom in or while the CONTROL key is depressed to zoom out.