Documentation

Documentation

The documentation is splitted into the basic and to the additional bundles.

Basic

org.eclipse.swtchart

http://www.swtchart.org/doc/index.html

Getting started

Installation

To use SWTChart as Eclipse plug-in, you can install it through update site:

1. open Add Repository dialog with Help > Install New Software... > Add...
2. specify update site shown at download page (e.g. https://download.eclipse.org/swtchart/releases/0.12.0/repository), and press Add button.
3. select Eclipse SWTChart, and press Next / Finish button.

To use SWTChart as standalone Java application without Eclipse, you can download jar files from download page and add to classpath.

How to show an empty chart

As a usual SWT widget, instantiate the class org.eclipse.swtchart.Chart giving a composite control and a style of control.

new Chart(composite, SWT.NONE);

That's it. An empty chart will be shown as below.

How to show series

Next step is to show series on chart. Let's show the following double array as a line chart.

double[] ySeries = { 0.3, 1.4, 1.3, 1.9, 2.1 };

1. Get a series set which is a container of series.

ISeriesSet seriesSet = chart.getSeriesSet();

2. Create a series giving a series type and a series identifier.

This time, you will show a line chart, so the series type is SeriesType.LINE, while the identifier can be any string like "line series".

ISeries series = seriesSet.createSeries(SeriesType.LINE, "line series");

3. Set the array for Y series.

series.setYSeries(ySeries);

Now, line series is shown on chart.

The range for X and Y axis is still 0 ~ 1. It should be adjusted so that series are fully shown.

4. Get an axis set which is a container of axes.

IAxisSet axisSet = chart.getAxisSet();

5. Adjust the range for all axes.

axisSet.adjustRange();

Finally, series are fully shown.

Concepts

Overview

As described in the class diagram below, Chart is composed of Legend, Title, Axis Set and Series Set. Axis Set and Series Set are a container of axes and series respectively. Axis is composed of Grid, Title and Axis Tick. Series has Series Label.

Chart

Plot Area

Plot Area is an area where series are drawn.

Since plot area is org.eclipse.swt.widgets.Composite, you can add key/mouse listeners or pop up menus on it.

Composite composite = chart.getPlotArea();
composite.addListener(SWT.MouseDown, new Listener() {
    public void handleEvent(Event event) {
        //
    }
});

Background

Background of chart is a background color except for legend and prot area. The background is set with org.eclipse.swt.graphics.Color.

The folowing example code sets the background to light red.

Color color = new Color(Display.getDefault(), 255, 128, 128);
chart.setBackground(color);

Background in Plot Area

Background in Plot Area is a background color in plot area. The background is set with org.eclipse.swt.graphics.Color.

The folowing example code sets the background in plot area to light red.

Color color = new Color(Display.getDefault(), 255, 128, 128);
chart.setBackgroundInPlotArea(color);

Orientation

Orientation of chart is a state indicating whether chart orientation is horizontal or vertical. The horizontal orientation means that the direction of X axis (Jan, Feb, Mar,...) is horizontal as shown on the left hand side in the screenshot below. The vertical orientation means that the direction of X axis is vertical as shown on the right hand side in the screenshot.

The orientation is set with the following value.

Description	Value
horizontal orientation	SWT.HORIZONTAL
vertical orientation	SWT.VERTICAL

The folowing example code sets the vertical orientation.

chart.setOrientation(SWT.VERTICAL);

Axis Set

Axis Set is a container of axes.

The folowing example code gets axis set from chart.

IAxisSet axisSet = chart.getAxisSet();

Axis Id

Axis Id is an identifier of axis. By default, axis set has X axis and Y axis with axis id 0. SWTChart supports multiple axes (e.g. having one X Axis and two Y axes), and axis id will be automatically assigned when creating additional axes.

int axisId = axisSet.createYAxis();

You can get an axis from axis set with axis id as below.

IAxis yAxis = axisSet.getYAxis(axisId);

You can delete the created axis in axis set with axis id as below.

axisSet.deleteYAxis(axisId);

Adjust Range

Adjust Range of axis set is an operation to adjust the range of all axes so that all series are fully shown. If you want to adjust the range of only a certain axis, please refer to Adjust Range.

axisSet.adjustRange();

Zoom

Zoom of axis set is an operation to zoom in or out the range of all axes. If you want to zoom only a certain axis, please refer to Zoom.

axisSet.zoomIn();
axisSet.zoomOut();

Axis

Direction

Direction of axis can be either X or Y. The direction cannot be changed once it is set when axis is created. Even if changing the orientation of chart, the direction of axis is persistent.

Position

Position of axis can be either primary or secondary. Primary means the position at bottom or left side of chart, while secondary means the position top or right side of chart. By default, the position is primary.

The position is set with the following enum value.

Description	Value
primary position	Position.Primary
secondary position	Position.Secondary

The folowing example code changes the position of Y axis from primary to secondary.

IAxis yAxis = axisSet.getYAxis(0);
yAxis.setPosition(Position.Secondary);

Range

Range of axis is a range shown on plot area.

The folowing example code sets the range of X axis between 1.5 and 3.5.

IAxis xAxis = axisSet.getXAxis(0);
xAxis.setRange(new Range(1.5, 3.5));

Log Scale

Log Scale is a state that the axis scale is logarithmic.

The folowing example code enables the log scale for Y axis.

IAxis yAxis = axisSet.getYAxis(0);
yAxis.enableLogScale(true);

Adjust Range

Adjust Range of axis is an operation to adjust the range of axis.

The folowing example code adjusts the range of Y axis.

IAxis yAxis = axisSet.getYAxis(0);
yAxis.adjustRange();

Zoom

Zoom of axis is an operation to zoom in or out the range of axis.

The folowing example code zooms in and out the range of Y axis.

IAxis yAxis = axisSet.getYAxis(0);
yAxis.zoomIn();
yAxis.zoomOut();

The folowing example code zooms in and out the range of Y axis at the given coordinate instead of at center of axis range.

IAxis yAxis = axisSet.getYAxis(0);
yAxis.zoomIn(0.5);
yAxis.zoomOut(0.5);

Scroll

Scroll of axis is an operation to scroll up or down the range of axis.

The folowing example code scrolls up or down the range of Y axis.

IAxis yAxis = axisSet.getYAxis(0);
yAxis.scrollUp();
yAxis.scrollDown();

Category

Category is a type of axis to show a chart categorizing multile series. It retuires category series to be shown as tick labels on axis.

The folowing example code enables a category axis with cagegory series (Jan, Feb,...).

IAxis xAxis = axisSet.getXAxis(0);
xAxis.setCategorySeries(new String[] { "Jan", "Feb", "Mar", "Apr", "May" });
xAxis.enableCategory(true)

Axis Tick

Foreground

Foreground of axis tick is a color of axis tick marks and labels. The foreground is set with org.eclipse.swt.graphics.Color.

The folowing example code sets the foreground color of X axis tick to red.

IAxisTick xTick = axisSet.getXAxis(0).getTick();

Color color = new Color(Display.getDefault(), 255, 0, 0);
xTick.setForeground(color);

Font

Font of axis tick is a font of axis tick labels which is set with org.eclipse.swt.graphics.Font.

The folowing example code sets the font size of X axis tick to 14 points.

IAxisTick xTick = axisSet.getXAxis(0).getTick();

Font font = new Font(Display.getDefault(), "Tahoma", 14, SWT.BOLD);
xTick.setFont(font);

Visibility

Visibility of axis tick is a state indicating whether to show axis line, axis tick marks and labels.

The folowing example code sets the X axis tick invisible.

IAxisTick xTick = axisSet.getXAxis(0).getTick();
xTick.setVisible(false);

Tick Mark Step Hint

Tick Mark Step Hint is a property to give a hint for calculating the size of tick mark step.

The folowing example code sets the tick mark step hint to 20 pixels.

IAxisTick xTick = axisSet.getXAxis(0).getTick();
xTick.setTickMarkStepHint(20);

Format

Format is a property to format the axis tick labels. java.text.DecimalFormat and java.text.DateFormat should be used for double[] and java.util.Date[] respectively.

The folowing example code sets the format for double array to attach the unit "M" to Y axis tick value.

IAxisTick yTick = axisSet.getYAxis(0).getTick();
yTick.setFormat(new DecimalFormat("#####.#M"));

The folowing example code sets the format for Date array to show hour and minute.

lineSeries.setXDateSeries(xSeries); // xSeries is an array of java.util.Date
IAxisTick xTick = axisSet.getXAxis(0).getTick();

DateFormat format = new SimpleDateFormat("HH:mm");
xTick.setFormat(format);

Extensions

org.eclipse.swtchart.extensions