Axis Scrolling

Although Chart FX for Java provides a wealth of properties to control how labels are displayed on an axis, the number of data points and the chart size become important factors as to how many labels you could fit in a chart or how much data is actually visible. In other words, some charts simply have too much data for the desired chart size and there's little you can do to improve the chart's readability.

Chart FX for Java provides an elegantly designed scroll bar that attaches to an axis and allows end users to zoom in and view portions of an entire chart. It is important to note that ALL axes in Chart FX for Java support scrolling, however, scrolling is only supported with Active charts.

Note: Scrolling is only supported for Active charts; When generating images the scroll thumb will be visible however not functional.

To enable scrolling you must enable the Chart object's setScrollable property as follows:


chart1.setScrollable(true);

The scroll bar will appear docked to the right next to the axis labels as depicted in the figure. The user can now drag the scroll bar thumb to a desired position in the chart.

The advantage of using a scroll bar is that data points will not be crunched inside the chart area and most points can show their respective labels. This enhances the chart's readability and allows the user to select portions of the chart at a time.

Controlling the Scroll Position programmatically

Although the scroll bar is an end user tool, you may want to control the number of points that are visible in a specific chart. This can easily be done with the setScrollView method supported by the Axis object.

For a categorical axis, this method receives the index of the points you want to see in the chart. For example, if you have 300 points and you want to force Chart FX to show points 30 to 60 in the categorical axis, you can set the SetScrollView method as follows:


chart1.getAxisX().setScrollView(30,60);

For a numerical axis, the SetScrollView method receives the values that want to show in a specific scroll view. For example, if your numerical axis is scaled between 0 and 300 and you want to set a scroll view between 10.5 and 50.5, you can set the ScrollView method as follows:


chart1.getAxisY().setScrollView(10.5,50.5);

Similarly, Chart FX for Java will dispatch a UserScroll event every time the user interacts with the axis scroll bar. This event is particularly useful if you need to synchronize several charts as the user interacts with a scroll bar.

Please refer to the Chart FX for Java Javadoc API for more information on the UserScroll event supported by Chart FX for Java.

The PixPerUnit Property

Essentially, the SetScrollView method uses the PixPerUnit property of the axis to control how labels are displayed. The PixPerUnit property allows you to specify the amount of physical pixels each tick mark will occupy in the chart. For example, if you have labeled the X-axis with long strings you may increase the size of each tick mark so that each label may be visible.

The PixPerUnit property is very useful when you want to create a scroll bar associated with the selected axis or to increase the separation between tick marks. The PixPerUnit effect varies depending on which type of axis to which it is applied, as follows:

PixPerUnit in a Categorical Axis

When you set a PixPerUnit to a categorical axis (e.g. X-axis), the value is an integer that will set the separation (physical distance measured in pixels) between major tick marks.

You may want to change the PixPerUnit value for a categorical axis when:

1) The labels associated with the chart are too long and do not fit in the allotted space. In this particular case, the PixPerUnit should be increased. If all points do not fit in one screen a scroll bar will be shown. This scenario requires the Scrollable Property to be set to TRUE.

2) You want to fit more points in one screen. In this particular case, the PixPerUnit should be decreased. You must be careful with Labels associated with each tick mark if the PixPerUnit is too small.

3) You want to view a specific amount of points per screen. In this particular case, we recommend the use of the SetScrollView method as it will allow you to set these values without any calculations on your part.

4) If you don't want to show a scroll bar, you may set the PixPerUnit to zero (0). This will remove the scroll bar for that axis and Chart FX for Java will set the appropriate PixPerUnit to fit all values in one screen.

PixPerUnit in a Numerical Axis

When applied to a numerical axis (e.g. Y-axis), the PixPerUnit property is very useful to display a scroll bar and allow users to scroll through data without affecting the scale (Min, Max, Step) of the axis.

Because a numerical axis can be displayed in different units (currency, scientific, date, etc.), it is sometimes difficult to imagine what a PixPerUnit measures. This concept is even more complex when we take into consideration that a numerical axis ranges in different values (millions, thousands, fractions, etc).

When applied to a numerical axis, the PixPerUnit value is no longer an integer. The general rule of thumb is to take the size allotted to the chart (in pixels) divide it by the Maximum in the numerical axis and then divide that number by the number of pages you want the scroll bar to have.

For example, if you have a 400 pixel chart that ranges between Min=0 and Max=1 million and you want to create a scroll bar that contains 5 pages, the PixPerUnit should be set to:

PixPerUnit = (400/1000000)/5 = 0.00008, this means there are 0.00008 pixels per unit in the Y-axis.

On the other hand, if the same chart would have ranged between 0 and 1, the PixPerUnit setting must be calculated as follows:

PixPerUnit = (400/1)/5 = 80

Setting the PixPerUnit to zero(0) will remove the scroll bar and let Chart FX for Java calculate the appropriate PixPerUnit value.