Configuring the Axis

The axes are automatically created by a chart, which uses by default only one y-axis. The first y-axis is also referred to as the main ordinate axis. Other y-axis can be added to a chart with the addYAxis method. You can determine the type of an axis with the getType method.

Within a chart, each y-axis forms a coordinate system with the x-axis. A coordinate system is an instance of the 0 class, and can be retrieved with the getCoordinateSystem method. Throughout the API of the library, both y-axis and coordinate systems are usually referenced by their index in the chart (starting at 0). For example, the third parameter to the scroll method specifies which y-axis should be modified:

// Translates by 20. the visible range of the first y-axis.

chart.scroll(0., 20., 0)

Example: Synchronizing Axes

You can synchronize two chart axes with the synchronizeAxis method. After this method is invoked, both charts share the same axis instance.

The complete source code of this example can be found in <installdir>/jviews-charts/codefragments/chart/axis-sync/src/AxisSync.java.

IlvChart topChart = new IlvChart();

// the topchart data source

IlvDefaultDataSource ds =

new IlvDefaultDataSource(new double[][]

{IlvArrays.randomValues(COUNT, 0, 50)},

-1,

new String[]{"Data Set 1"},

null);

topChart.setDataSource(ds);

// add some interactors to be able to play with the axis range

topChart.addInteractor(new IlvChartZoomInteractor());

topChart.addInteractor(new IlvChartPanInteractor());

// the bottom chart. This chart shares the same x-axis with topChart.

IlvChart bottomChart = new IlvChart();

ds = new IlvDefaultDataSource(new double[][]

{IlvArrays.randomValues(COUNT, 0, 50)},

-1,

new String[]{"Data Set 2"},

null);

bottomChart.setDataSource(ds);

// synchronize the x-axis with the one from topchart. We also want to

// synchronize the plot area of both charts so that grids are aligned.

bottomChart.synchronizeAxis(topChart, IlvAxis.X_AXIS, true);

Axis properties

The following table lists the properties of an axis:

Property	Methods	Default Value
reversed	setReversed isReversed	false
adjusting	setAdjusting isAdjusting	false
autoDataMin	setAutoDataMin isAutoDataMin	true
autoDataMax	setAutoDataMax isAutoDataMax	true
autoVisibleRange	setAutoVisibleRange isAutoVisibleRange	true

Reversing an Axis

The setReversed method allows you to toggle the reversed property of an axis. The values along a reversed axis are considered in backward order. For example, reversing the x-axis affects the orientation of a polar projector:

The projector is oriented counterclockwise if the x-axis is not reversed.

The projector is oriented clockwise if the x-axis is reversed.

Specifying the Automatic Modes of Axis Ranges

Three properties define the automatic range modes of an axis, as described in section Changing the axis ranges:

isAutoDataMin indicates whether the minimum data value is automatically computed. You can disable the automatic mode with the setAutoDataMin method, or by explicitly specifying the minimum data value.

isAutoDataMax indicates whether the maximum data value is automatically computed. You can disable the automatic mode with the setAutoDataMax method, or by explicitly specifying the maximum data value.

isAutoVisibleRange indicates whether the visible range is synchronized with the data range. You can disable the synchronization of the setAutoVisibleRange method, or by explicitly specifying the visible range.

Setting the Axis in an Adjusting State

The setAdjusting method lets you toggle the adjusting state of an axis. This state is used when firing AxisEvent events, so that registered listeners know that the received notifications are part of a set of changes.

Changing the axis ranges

An IlvAxis object defines two ranges:

The data range, which specifies the limits of the data values along this axis. This range can be unbounded, which means that the minimum and maximum data values are undefined.

The visible range, which specifies the visible data interval along this axis.

The axis ensures that the visible range is always contained within the data range:

dataMin <= visibleMin <= visibleMax <= dataMax

The data range of an axis is specified according to two modes:

Automatic mode

In this mode, the data range is computed by the chart. The chart delegates this calculation to an IlvDataRangePolicy object. The default policy computes the data range so that it fits the data actually displayed by the chart.

Manual mode

The setDataMin, setDataMax, or setDataRange methods allow you to indicate the minimum and maximum data values.

When you call a method to explicitly set a value for the minimum data and maximum data value, you toggle off the automatic mode for the corresponding value. For example, calling the setDataMin method disables the automatic calculation of the minimum data.

The visible range of an axis also follows two modes:

The visible range can be synchronized with the data range. In that case, the visible range is updated each time the data range is modified.

The visible range can be explicitly specified with the setVisibleMin, setVisibleMax setVisibleMax, or setVisibleRange methods. By calling one of these methods, you toggle off the synchronization of the visible range with the data range.

You can find a list of the properties related to the axis data range and the axis visible range in section Axis properties.

Setting the axis transformer

An optional transformation can be associated with an IlvAxis instance. This transformation is applied to every data value along this axis before it is converted to display coordinates.

Axis transformers are implemented by subclasses of the IlvAxisTransformer abstract class. Each concrete subclass must implement two abstract methods:

apply, which performs the forward transformation.

inverse, which performs the inverse transformation.

You can override the default implementation of the other methods of the IlvAxisTransformer class. For example, the apply method uses the elementary transformation on all the values of the specified array. A faster implementation can sometimes be found by making intermediate calculations only once.

The following predefined transformations are available in the JViews Charts library:

IlvAffineAxisTransformer applies an affine transformation.

IlvLogarithmicAxisTransformer applies a logarithmic transformation.

IlvLocalZoomAxisTransformer applies a scaling factor to data values within a given range.

Local Zoom shows the effect of an IlvLocalZoomAxisTransformer set on the x-axis of a chart:

Local Zoom

Listening to axis events

The AxisEvent class represents the base class for axis events. Listeners can be registered to receive these events with the addAxisListener and removeAxisListener methods.

Range Events

These events are sent when the visible range or the data range of an axis changes. When this happens, two AxisRangeEvent events are fired:

A first event is sent before the change actually occurs. This event is also called an about-to-change event. It gives to the listeners an opportunity to constrain the proposed new value of the range with the setNewMin and setNewMax methods.

A second event is sent after the change. The previous values of the range can be retrieved with the getOldMin and getOldMax methods.

You can check whether an event is an about-to-change event with the isAboutToChangeEvent method. The following code shows how a listener can be used to coerce the visible range of an axis:

axis.addAxisListener(new AxisListener() {

/**

* Constrain visible min and visible max to integer values.

public void axisRangeChanged(AxisRangeEvent ev) {

if (ev.isChangedEvent() || !ev.isVisibleRangeEvent()) return;

ev.setNewMin(Math.floor(ev.getNewMin()));

ev.setNewMax(Math.ceil(ev.getNewMax()));

}

public void axisChanged(AxisChangeEvent evt) {}

});

Change Events

The change events are implemented by the AxisChangeEvent class. These events are sent when one of the following changes occur:

The reversed property of the axis has been modified. The type of the event is AxisChangeEvent.ORIENTATION_CHANGE.

The adjusting property of the axis has been modified. The type of the event is AxisChangeEvent.ADJUSTMENT_CHANGE.

The transformer of the axis has changed. The type of the event is AxisChangeEvent.TRANSFORMER_CHANGE. This type of event covers all the changes that can affect the transformer. It also includes setting the transformer or removing it from the axis.

Handling chart resizing

The way a change of the chart size affects the visible range of the axis is handled through a resizing policy. A resizing policy determines whether the visible range of the axis of a Cartesian chart is modified when the chart is resized.

Resizing policies are implementations of the IlvChartResizingPolicy interface and are set on a chart by means of the setResizingPolicy method.

The JViews Charts package provides a default implementation of this interface by means of the IlvChartResizingPolicy.DEFAULT_POLICY class. This class expands the visible range of the coordinate axis when a chart area is resized so that the scaling factor of the Cartesian projection keeps the same value.

By default, a chart has no resizing policy, that is, the visible range of the axis is not changed when the chart size changes.

NOTE A resizing policy applies only to Cartesian charts.