BIRT/FAQ/Charts2.1

Download

Where can I get the Eclipse Chart Engine distribution?

The Chart package is included in the main BIRT distribution, but you can get it separately from the download page. Select the BIRT version you need, and choose the Chart Engine distribution (which contains the chart examples plugin). You can also get it from CVS directly, if you wish to get the latest source as well as the unit tests.

Features

What are the supported chart types?

The following table summarizes the available chart types.

Type	SubTypes	Dimensions
		2D			2D with depth (3D effect)	3D (real 3D rendering)
Bar	Side-by-side	Stacked	Percent Stacked	yes	yes	yes
Line	Side-by-side	Stacked	Percent Stacked	yes	yes	yes
Area	Side-by-side	Stacked	Percent Stacked	yes	yes	yes
Stock	Candle Stick	Bar Stick	-	yes	no	no
Scatter	-	-	-	yes	no	no
Pie	-	-	-	yes	yes	no
Meter	Single Dials	Superimposed Dial	-	yes	no	no

Integration

Can I use the Eclipse Chart engine in my own application?

Yes. A primary goal of the Eclipse Chart Engine project is to provide a package that can be used both with the BIRT reporting components as well as standalone.

As such, it is a complete Charting library with both a Chart Builder UI and a Chart Engine, with an out-of-the-box integration with BIRT. It can run outside of Eclipse as well and provides numerous extension points to add new capabilities, or to integrate in any application.

What JARs are needed on the classpath to deploy the Eclipse Chart Engine?

The following JARs and folders need to be included in your CLASSPATH at build/run time. They are all available in the chart engine download, except for the EMF plugins you need to get from the Eclipse EMF download site. Note that you don’t necessarily need all of those if your application do not use certain functionalities.

Chart engine libraries:

• org.eclipse.birt.chart.device.extension_2.1.0.jar
• org.eclipse.birt.chart.device.svg_2.1.0.jar
• org.eclipse.birt.chart.device.swt_2.1.0.jar
• org.eclipse.birt.chart.engine.extension_2.1.0.jar
• org.eclipse.birt.chart.engine_2.1.0.jar
• org.eclipse.birt.chart.ui.extension_2.1.0.jar
• org.eclipse.birt.core.ui_2.1.0.jar
• org.eclipse.birt.core_2.1.0.jar
• Any jar from a custom extension plugin you wrote.

Third party dependencies:

• org.mozilla.rhino_1.6.0 (folder)
• org.apache.commons.codec_1.3.0 (folder)
• org.apache.batik_1.6.0 (folder)
• org.apache.batik.pdf_1.6.0 (folder)
• org.apache.xerces_2.8.0 (folder)
• org.eclipse.emf.common_2.x.y.jar
• org.eclipse.emf.common.resources_2.x.y.jar
• org.eclipse.emf.ecore_2.x.y.jar
• org.eclipse.emf.ecore.resources_2.x.y.jar
• org.eclipse.emf.ecore.xmi_2.x.y.jar

OSGi dependencies

Eclipse 3.2 now uses OSGi to load the plugins, so if you want to benefit from the extension mechanism outside Eclipse, you will need the OSGi plugins. If you use STANDALONE (see below), you won’t need them though. Get the BIRT runtime package from the download site to see how plugins are organized outside Eclipse with OSGi support.

How to configure the Chart Engine environment?

Any application using the Chart Engine needs to set either one of those system properties (they should not be used together).

STANDALONE: if you don’t need any extension plugin, like the PDF plugin for instance. No value is needed.

BIRT_HOME: if you need chart extensions plugins to be loaded. Set the value to the directory containing the chart and extensions plugins, such as the PDF plugin (inside a plugins subfolder).

To set the property you can use System.setProperty() or set it in your java command line through –D. Example: java –DSTANDALONE MyApplication

Can I use the Chart Builder in my application?

Yes, the Chart Builder can be used outside of a BIRT report, and can be integrated in any Java environment. Look at the ChartWizardLauncher example in the org.eclipse.birt.chart.example plugin.

The Chart Builder is fully extensible and can take advantage of any chart model/engine extensions you write, it can also be integrated in any Data environment. It has no dependency on other BIRT reporting plugins.

How do I show a chart in my Eclipse RCP application?

You could create a plug-in with a ViewPart extension that creates an SWT canvas and notifies a PaintListener implementation where the chart rendering code may be written. Look at the SWT viewer examples in the examples plugin.

Chart Output Formats

What output formats does the chart engine support?

Internally, the charting engine writes to device independent primitives. This means that any output format may be plugged in by writing a device extension. A device refers to an implementation that translates rendering primitives into a specific file format. Release 2.0 provides the following:

 Static images (PNG, JPG, BMP) with optional ImageMap support.

 PDF document

 SWT graphics (GC)

 SWING graphics (Graphics2D)

 SVG (Scalable Vector Graphics)

In addition, custom extensions may be written to support additional file formats.

The device rendering framework is tailored to suit the needs of rendering a comprehensive set of graphics primitives, elaborate text layout (focused on typical usage of text rendering in charts), and event handling. The framework is optimized for performance.

What is the best static output format?

Each format has some advantages, so here is a quick guide to select the best output format for your needs:

SVG has a very good interactivity support, but requires the browser to support SVG. For IE, it means you need to install a SVG plugin.

PNG has a more limited interactivity support, but supports tooltips and hyperlinks through an HTML ImageMap. It is probably the best choice over JPG and BMP as it supports transparency, 32 bits colors, and compression without loss. It is widely supported across browsers. The rendering quality of text is also slightly better than SVG for small fonts, although this should be corrected in a future release.

What chart output formats are supported within BIRT reports?

The following table shows from which version each chart output format is supported in a BIRT report. For instance SVG is supported in HTML reports since version 2.0. Note that GIF support has been dropped in 2.1, and can be safely replaced by PNG.

Chart Output Format	SVG	PNG	PDF	BMP	JPG
HTML Report	2.0	1.0	2.1	2.0	2.0
PDF Report	-	2.0	2.1	2.0	1.0

Can the chart package output SVG or PDF?

SVG output is supported from release 1.0.1. It has been contributed by IBM as a chart extension plugin org.eclipse.birt.chart.svg, which is included in the BIRT distribution.

PDF is supported from release 2.1. It has also been contributed by IBM as an extension, and requires the batik, batik.pdf and xerces plugins.

What are the known limitations of SWT rendering?

There are some known SWT issues with Linux, and some anti-alias problems when drawing arcs, but those are relatively minor issues.

Chart Terminology

What is the difference between "2D with depth" and "3D"?

2D with depth charts are simply 2D charts with a 3D effect. This can make the charts generally look nicer and is normally sufficient for most cases, like Pie Charts or Bar Charts with a single Series. It is theoretically faster to render than 3D charts as there are no 3D computations done.

3D charts are represented by a 3D engine using lighting, real perspective, and allowing rotations. 3D charts are particularly useful for Charts with Axes with multiple series, as it adds a third Z-Axis to plot different series side by side in a third dimension.

What does "Inherit Report Data" do in Chart Builder?

"Inherit Report Data" means that the Chart will use the data available from its container. It only can work if the chart container is a report item such as a table or list item. In this case, depending on the cell where it is located, different rows will be available. A good example is when you place a chart within a group header or footer, the chart will use all the rows for that group, as a data input.

What do "Orthogonal’ and "Base" mean?

This is the old 1.0.x terminology to distinguish between the values plotted on the chart, and what they represent. The 2.0 release now uses Categories (Base) and Values (Orthogonal), as it is more representative. The Categories are plotted on the X-Axis in case of Chart with axes, while the Values are represented on the Y-Axis. Note that this terminology of Base and Orthogonal is still present in the API and code.

Chart Rendering

How do I externalize text that needs to retrieve a runtime value from a locale specific message file?

This depends on whether you are using the Chart within a BIRT report or in standalone mode.

BIRT Report Context

Several text components in a report design may contain externalized text references. The value of these components would be specified using the format:

key=<default value>

As an example, the chart title could be defined as:

sales.chart.title=Sales Title

At generation/presentation time, a lookup for the value for key=sales.chart.title would be performed against the locale specific property text resource bundle associated with the report design that incorporates the chart instance. If the resource bundle is not found or the externalized message key cannot be located, the default value will be presented.

Standalone Mode

In that case, you can use the IMessageLookup interface. By implementing it, it will allow the chart engine to retrieve the value of a given key. If the key is not found it will use the default value.

The key and default values are represented by an expression as Key=<default value>. This is set in the chart model for each static text property. At generation time, a lookup is performed for the key with IMessageLookup. If IMessageLookup does not return a value for the key, the default value will automatically be used.

Extensions Developers

If you are writing a chart extension, you need to make sure your code will support internationalization. Externalized text may be retrieved via the RunTimeContext instance which is available at chart generation time via the following API (independently of BIRT/Standalone):

String externalizedMessage(String key)

How do I intercept the chart generation/rendering process and alter the content of the chart using custom business logic?

The chart library provides support for writing custom business logic via JavaScript or Java. A detailed set of low level callback methods are provided to intercept the generation and rendering process and insert custom business logic. Look at the Chart Script specifications for more details: http://www.eclipse.org/birt/wiki/index.php?n=BPS.BPS18

Chart Engine Extensions

How do I modify the EMF Chart Model?

In some cases, you might want to update the model to add new types for instance. Note that if you change the model, you will not be able to update to a later version without merging your changes.

The steps are:

• Get the chart engine plugin from CVS
• Update the xsd file in the xsd directory with your model changes, using a xml or schema editor
• In the src/model folder, right click on the model.genmodel file and choose "Reload…"
• In the popup window check the box
• Click next and finish
• Double click on model.genmodel to open it
• Right click on the root Model node and choose "Generate Model". It will update the chart model source code automatically.

How do I write a new series type that uses a custom data element?

An example of a chart type that uses a custom data element that already exists in the system is a Stock series chart. Each data element (held in a stock data set) holds four numerical values:

a. High

b. Low

c. Open

d. Close

These four values are encapsulated in a StockEntry class available in package org.eclipse.birt.chart.datafeed

A collection or array of StockEntry instances are wrapped in a StockDataSet instance and associated with a Stock series. At runtime, a StockDataSetProcessor (associated with a Stock series via an extension point definition) is capable of performing the following functions with a StockDataSet:

A] Build a stock data set by parsing a comma separated list of StockEntry values

B] Compute the smallest value of (high, low, open, close) of all StockEntry values

C] Compute the largest value of (high, low, open, close) of all StockEntry values

D] Capable of extracting values from resultset columns and creating StockEntry instances that are fed to a StockDataSet

As can be seen above, the following tasks are needed for a new custom dataset associated with a series:

Task-1: Update the appropriate schema files

Extend …/xsd/model.xsd from plug-in project org.eclipse.birt.chart.engine with a section like this (for the new CustomSeries being added):

<!-- Custom Series -->

<xsd:complexType name="CustomSeries">

<xsd:annotation>

<xsd:documentation xml:lang="en">

Custom series documentation goes here.

</xsd:documentation>

</xsd:annotation>

<xsd:complexContent>

<xsd:extension base="component:Series">

<xsd:sequence>

<xsd:element name="Property1" type="Type1">

<xsd:annotation>

<xsd:documentation xml:lang="en">

Documentation for Property1 goes here.

</xsd:documentation>

</xsd:annotation>

</xsd:element>

<xsd:element name="Property2" type="Type2">

<xsd:annotation>

<xsd:documentation xml:lang="en">

Documentation for Property2 goes here.

</xsd:documentation>

</xsd:annotation>

</xsd:element>

</xsd:sequence>

</xsd:extension>

</xsd:complexContent>

</xsd:complexType>

Note that the newly added custom series subclasses the component: org.eclipse.birt.chart.model.component.Series

This example illustrates two properties associated with every instance of the newly created CustomSeries

This will result in creation of:

org.eclipse.birt.chart.model.component.CustomSeries

org.eclipse.birt.chart.model.component.impl.CustomSeriesImpl

Now, extend …/xsd/data.xsd from plug-in project org.eclipse.birt.chart.engine with a section like this (for the new CustomDataSet being added):

<!-- Custom Data Set -->

<xsd:complexType name="CustomDataSet">

				<xsd:annotation>
			<xsd:documentation xml:lang="en">
			Documentation for new dataset type
			</xsd:documentation>
				</xsd:annotation>
				<xsd:complexContent>
			<xsd:extension base="DataSet">
				<xsd:sequence/>
			</xsd:extension>
				</xsd:complexContent>
				</xsd:complexType>

Note that the newly added custom data set subclasses the interface: org.eclipse.birt.chart.model.data.DataSet

This will result in creation of:

org.eclipse.birt.chart.model.data.CustomDataSet

org.eclipse.birt.chart.model.data.impl.CustomDataSetImpl

Task-2: Regenerate and incrementally update the existing Java source

Use EMF’s SDK to regenerate the Java source for all XSDs defined under xsd/

Ensure that the Java source is generated into a folder that contains the existing source. This ensures that existing manual changes are preserved in the existing Java source and only the new sections are incrementally appended.

Details on how to generate Java source using XSDs is available at:

http://download.eclipse.org/tools/emf/scripts/docs.php?doc=tutorials/xlibmod/xlibmod.html

Update the generated Java source into the org.eclipse.birt.chart.engine plug-in project

Task-3: Write the data set processor implementation

Create a new plug-in project (use a suitable name e.g. org.eclipse.birt.chart.dataset.extension)

Write a class CustomDataSetProcessor that subclasses org.eclipse.birt.chart.datafeed.DataSetAdapter (implements org.eclipse.birt.chart.datafeed.IDataSetProcessor). Fill in the implementation for each of the method declarations as appropriate.

Define an ’extension’ in this newly created plug-in project as follows:

extension point: org.eclipse.birt.chart.engine.datasetprocessors

series: org.eclipse.birt.chart.model.type.impl.CustomSeriesImpl

processor: org.eclipse.birt.chart.datafeed.CustomDataSetProcessorImpl

At this point, the engine API is updated to work with the newly defined CustomSeries and its associated CustomDataSet. However, there is no renderer capable of rendering values contained in the CustomDataSet on the plot.

Let us assume that we would like the CustomDataSet to contain DateRange (start, end) elements to be plotted on a datetime axis scale. A custom series renderer class would have to be written to support this.

Task-4: Writing a custom series renderer

A datetime range data structure is typically associated with a simple Gantt chart indicating start and end date/time values for the graphic element plotted along a datetime value scale. A Gantt graphic element renderer would be responsible for drawing rectangular bars (with possible captions) on a plot that could be rendered normally or transposed, in 2D or 2D with depth requiring the 2D bars to be extruded.

The custom series renderer could be either written in a new plug-in project or by reusing the same plug-in project defined in task 3.

Define the extension class as org.eclipse.birt.chart.render.Gantt which subclasses org.eclipse.birt.chart.render.AxesRenderer (because the Gantt graphic elements will be rendered on a plot that uses the Axis rendering framework).

Add an extension point as follows:

extension point: org.eclipse.birt.chart.engine.modelrenderers

series: org.eclipse.birt.chart.model.type.impl.CustomSeriesImpl

renderer: org.eclipse.birt.chart.render.Gantt

Implement all abstract methods that are subclassed in the Gantt core implementation series rendering class. These are:

void renderSeries(IPrimitiveRenderer ipr, Plot p, ISeriesRenderingHints isrh) throws ChartException

void renderLegendGraphic(IPrimitiveRenderer ipr, Legend lg, Fill fPaletteEntry, Bounds bo) throws ChartException

void compute(Bounds bo, Plot p, ISeriesRenderingHints isrh) throws ChartException

That’s all it takes to now create Gantt charts with a custom dataset via the chart API. If user interface property sheets need to be defined for specifying properties (data and attributes) associated with the Gantt chart, this is also possible. Refer to the documentation on how to extend the user interface for custom series types.

How does the chart library integrate with BIRT?

The following table summarizes the integration between the charting system and the BIRT reporting system. This can serve as a reference/example when integrating the charting system with your own application.

The plug-in org.eclipse.birt.chart.reportitem defines several classes that are responsible for integrating charts with BIRT. This plug-in is directly dependent on core chart plug-ins and its dependent libraries and indirectly dependent on extension chart plug-ins.

The following interface adapters were subclassed and methods implemented in this reportitem plug-in:

Interface	No-op Adapter	Purpose
IReportItemFigureProvider	ReportItemFigureProvider	Actual class: ChartReportItemUIImpl Links extended item to the BIRT UI as a report item and provides UI related services. Also links the builder and the figure for design-time representation.
IReportItemBuilderUI	ReportItemBuilderUI	Actual class: ChartReportItemBuilderImpl Represents a extended item user interface builder to specify extended item definition.
IFigure	Figure	Actual class: DesignerRepresentation Subclassed and overridden the paint(Graphics) method to draw the extended item in the designer layout.
IReportItemFactory	ReportItemFactory	Actual class: ChartReportItemFactoryImpl Capable of creating new extended item ’IReportItem’ instances. Also provides hooks to retrieve localized messages.
IReportItem	ReportItem	Actual class: ChartReportItemImpl Holds instances of the underlying extended item model(s). Also returns available property definitions and hooks to set/get property definitions and serialize/deserialize/clone the model(s).
IElementCommand	ElementCommand	Actual class: ChartElementCommandImpl Attaches the extended item to the undo/redo framework and links to the command stack.
IChoiceDefinition	ChoiceDefinition	Actual class: ChartChoiceDefinitionImpl Used in exposing a property type that may contain a limited set of enumerated values.
IPropertyDefinition	PropertyDefinition	Actual class: ChartPropertyDefinitionImpl Used in defining any extended property that needs to be exposed in the property view. This includes the property name, type and default value.
IMessageLookup	-	Actual classes: BIRTMessageLookup, BIRTDesignerMessageLookup, ChartBuilderMessageLookup Externalize strings in chart rendered in BIRT reports, BIRT Designer and Chart Builder
IActionEvaluator	ActionEvaluatorAdapter	Actual class: BIRTActionEvaluator Invocated at generation time to retrieve the report expressions contained in interactive BIRT Hyperlinks.
IActionRenderer	ActionRendererAdapter	Actual class: BIRTActionRenderer Used at presentation time to convert BIRT dynamic Hyperlinks into standard HTTP Hyperlinks.
IStyleProcessor	-	Actual class: ChartReportStyleProcessor Used to map BIRT styles to Chart formatting properties
IDataServiceProvider	DefaultDataServiceProviderImpl	Actual class: ReportDataServiceProvider Used by chart builder to retrieve report data.
IDataRowExpressionEvaluator	DataRowExpressionEvaluatorAdapter	Actual class: BIRTDataRowEvaluator Used for both generation/presentation: evaluates a BIRT expression with a row context.
IReportItemQuery	ReportItemQueryBase	Actual class: ChartReportItemQueryImpl This is activated at runtime to invoke the generation process for a chart. Generation involves extended item query preparation, data binding (linking the BIRT defined data set to the chart) and creation of the device-independent display-server specific pre-computed chart structure.
IReportItemGeneration	ReportItemGenerationBase	Actual class: ChartReportItemGenerationImpl This is the generation step: the chart expressions are evaluated and registered in the report document.
IReportItemPresentation	ReportItemPresentationBase	Actual class: ChartReportItemPresentationImpl This step follows the generation step and is responsible for creating the device-specific finished chart output. In the context of BIRT, the extended item output must be provided as an image file format provided as a byte[] or as an InputStream.

Note:

Items in BLUE refer to the UI related interfaces.

Items in GREEN refer to the common interfaces between UI and runtime.

Items in PURPLE refer to Chart engine interfaces

Items in RED refer to the runtime related interfaces.