Skip to content

Documentation

Jump to bottom
Philip Wenig edited this page Aug 22, 2020 · 14 revisions

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.

emptychart

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();
  1. 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");
  1. Set the array for Y series.
series.setYSeries(ySeries);

Now, line series is shown on chart.

unscaled_linechart

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

  1. Get an axis set which is a container of axes.
IAxisSet axisSet = chart.getAxisSet();
  1. Adjust the range for all axes.
axisSet.adjustRange();

Finally, series are fully shown.

linechart

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.

class_diagram

Chart

Plot Area

Plot Area is an area where series are drawn.

plot_area

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.

background

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.

background_in_plotarea

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

orientation

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 Axis: Adjust Range.

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 Axis: Zoom.

zoom.png

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

position

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.

logscale

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.

adjust_yrange

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.

zoom_y

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.

scroll

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.

category

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.

axistick_foreground

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.

axistick_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.

axistick_visibility

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.

axistick_stephint

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.

axistick_format

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);

Grid

Foreground

Foreground of grid is a color of grid line which is set with org.eclipse.swt.graphics.Color.

grid_foreground

The folowing example code sets the foreground of X grid to red.

IGrid xGrid = axisSet.getXAxis(0).getGrid();

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

Style of grid is a line style of grid line defined with the enum LineStyle.

Description Value Style
solid LineStyle.SOLID solid
dash LineStyle.DASH dash
dot LineStyle.DOT dot
dash dot LineStyle.DASHDOT dashdot
dash dot dot LineStyle.DASHDOTDOT dashdotdot
none LineStyle.NONE

The folowing example code sets the line style of X grid to solid.

IGrid xGrid = axisSet.getXAxis(0).getGrid();
xGrid.setStyle(LineStyle.SOLID);

Series Set

Series Set is a container of series.

The folowing example code gets series set from chart.

ISeriesSet seriesSet = chart.getSeriesSet();
Series Id

Series Id is an identifier of series. When creating series, series type and series id have to be given.

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

You can get series from series set with series id as below.

ISeries series = seriesSet.getSeries(seriesId);

You can delete series in series set with series id as below.

seriesSet.deleteSeries(seriesId);
Series Order

Series Order is an order to draw series on chart. Typically, the series order can be important when enabling stack series or when series is overlaid by other series.

The series order is determined by the order of creating series, and can be re-ordered with following methods.

seriesSet.bringForward("line series");
seriesSet.sendBackward("line series");
seriesSet.bringToFront("line series");
seriesSet.sendToBack("line series");

Series

Visibility

Visibility of series is a state indicating whether to show series.

The folowing example code sets the series invisible.

ISeries series = seriesSet.getSeries(seriesId);
series.setVisible(false);
Series Type

Series Type is a property which can be either line series SeriesType.LINE or bar series SeriesType.BAR. When creating series, series type and series id have to be given.

String seriesId = "line series";
ISeries series = seriesSet.createSeries(SeriesType.BAR, seriesId);
Stack

Stack of series is a property to stack multiple series.

stack

The folowing example code stacks the bar series.

barSeries1.enableStack(true);
barSeries2.enableStack(true);

Line Series

Symbol Type

Symbol Type is a tyle of plot symbol defined with the enum PlotSymbolType.

Description Value Style
circle PlotSymbolType.CIRCLE circle
square PlotSymbolType.SQUARE square
diamond PlotSymbolType.DIAMOND diamond
triangle PlotSymbolType.TRIANGLE triangle
inverted triangle PlotSymbolType.INVERTED_TRIANGLE inverted_triangle
cross PlotSymbolType.CROSS cross
plus PlotSymbolType.PLUS plus
none PlotSymbolType.NONE

symboltype

The folowing example code sets the symbol type to square.

series.setSymbolType(PlotSymbolType.SQUARE);
Symbol Size

Symbol Size is a side length of square to draw series symbol. If symbol type is circle, symbol size is equal to diameter.

symbolsize

The folowing example code sets the symbol size to 6 pixels.

series.setSymbolSize(6);
Symbol Color

Symbol Color is a color of series symbol which is set with org.eclipse.swt.graphics.Color.

symbolcolor

The folowing example code sets the symbol color to red.

Color color = new Color(Display.getDefault(), 255, 0, 0);
series.setSymbolColor(color);

The following example code sets the different symbol color for each data point.

Color[] colors = ...
series.setSymbolColor(colors);
Line Style

Line Style of line series is a line style defined with the enum LineStyle.

Description Value Style
solid LineStyle.SOLID solid
dash LineStyle.DASH dash
dot LineStyle.DOT dot
dash dot LineStyle.DASHDOT dashdot
dash dot dot LineStyle.DASHDOTDOT dashdotdot
none LineStyle.NONE

series_linestyle

The folowing example code sets the line style to dot.

series.setLineStyle(LineStyle.DOT);
Line Color

Line Color is a color of line series which is set with org.eclipse.swt.graphics.Color.

series_linecolor

The folowing example code sets the line color to red.

Color color = new Color(Display.getDefault(), 255, 0, 0);
series.setLineColor(color);
Line Width

Line Width of line series is a width to draw line and plot symbol.

series_linewidth

The folowing example code sets the line width to 3 pixels.

series.setLineWidth(3);
Anti-Aliasing

Anti-Aliasing of line series is a property to set the anti-aliasing value for drawing line of line series.

The anti-aliasing is set with the following value.

Description Value
enable anti-aliasing SWT.ON
disable anti-aliasing SWT.OFF
set anti-aliasing default SWT.DEFAULT

If number of data points is too large, the series is drawn as a collection of dots rather than lines. In this case, the anti-alias doesn't really make effect, and just causes performance degradation. Therefore, client code may automatically enable/disable the anti-alias for each series depending on the number of data points, or alternatively may let end-user configure it.

The folowing example code enables anti-aliasing for line series.

series.setAntialias(SWT.ON);
Area

Area of line series is a property to fill between line series and axis with color. If there are multiple stacked series with category axis, the area between line series will be filled.

series_area

The folowing example code enables the area chart.

series.enableArea(true);
Step

Step of line series is a property to show line with step.

series_step

The folowing example code enables the step chart.

series.enableStep(true);

Bar Series

Bar Padding

Bar Padding is a padding size of bar in percentage. By default, the bar padding is 20%.7

series_barpadding

The folowing example code sets the bar padding to 50%.

series.setBarPadding(50);

Extensions

org.eclipse.swtchart.extensions

Copyright (C) 2008-2020 Eclipse SWTChart project. Eclipse Public License 2.0 (https://www.eclipse.org/legal/epl-2.0)

Clone this wiki locally