The chart element in a report design extends the basic BIRT report item through the org.eclipse.birt.report.model.api.ExtendedItemHandle class, so it supports the same standard properties and functionality as all other report items. To
access the chart item using the design engine API, call the ExtendedItemHandle
.getProperty( ) method with an argument of chart.instance. This call returns an org.eclipse.birt.chart.model.Chart object. All chart types implement this interface through one of the classes, ChartWithAxesImpl, ChartWithoutAxesImpl, and DialChartImpl from the org.eclipse.birt.chart.model.impl package. Cast the Chart object to the appropriate class to change its properties.

ChartWithAxesImpl is the most commonly used chart class. This class supports area, bar, bubble, cone, difference, Gantt, line, pyramid, scatter, stock, and tube charts. ChartWithoutAxesImpl supports pie and radar charts. DialChartImpl supports meter charts. Many of these chart types provide subtypes. For example, a bar chart has stacked, percent stacked, and side‑by‑side subtypes that affect the appearance of a multi-series bar chart.

The key visual components of a chart are movable areas known as blocks that are defined by the interface org.eclipse.birt.chart.model.layout.Block. Blocks include the plot, title, and legend areas. A charting application can change the location of the title and legend areas with respect to the plot area.

The key data component of a chart is the series. The series controls the set of values to plot and how to group those values. Charts display the values from series as data points in a chart with axes and as slices or pointers in a chart without axes. A charting application can define series values statically as a data set or dynamically as a query. The chart engine also provides extension points to support custom data set types.

The chart engine requires placing all data in an object that implements the chart org.eclipse.birt.chart.model.data.DataSet interface before generating the chart. The following interfaces in the org.eclipse.birt.chart.model.data.impl package extend the DataSet interface:

Each interface has a corresponding implementation class that supplies a static create method to initialize a data structure. For example, the following code creates a static NumberDataSet for a series in a chart:

The chart engine does not support sorting or grouping on a static data set. A chart displays one data point for every value in a static data set in the order provided.

The chart engine supports sourcing data from a dynamic source, which includes BIRT data sets and java.sqlResultSet objects. In these cases, the binding phase generates the chart data sets based on the expressions defined in the model for each series in the chart. After completing this phase, each Chart series binds to one of the chart data sets listed in the static data section.

A series is a set of plotted values in a chart. BIRT uses a series definition object to define what data a series contains. For example, row["month"] populates a series with the month column from a BIRT data set bound to a chart. This series definition object results in a run-time series that is bound to a supported chart data set type when the chart generates.

BIRT also supports defining groups and sorting in a series definition. When using these features, BIRT creates additional run‑time series as necessary, each with its own chart data set.

For example, if a BIRT report contains a data set having three columns, such as the product name, amount sold, and month sold, you can create a bar chart to display the data. The category series contains the product and the value series contains the amount. Using the category series as the x-axis and the value series as the y-axis, the chart model produces two run-time series when generating the chart. You can add the month to the y-axis series to group the data and produce multiple run-time series. The category series and the value series can contain up to twelve run-time series, one for each month.

All run-time series for a chart must have the same number of data points. To get the run-time series for a series, call the getRunTimeSeries( ) method for the specific series definition. Listing 6‑2 gets a run-time series and sets the first bar series to have a riser type of triangle.

Some chart types use nested SeriesDefinitions objects. For example, a pie chart creates a top-level series definition that stores category series information. This top-level series definition also contains another nested series definition that stores the information for the value series.