A Java program can open an existing BIRT report design file and alter the content of the report before displaying or saving the report. The chapter on programming BIRT describes how to open a report design file using the BIRT engine and model APIs. This section describes how to use the BIRT charting API to modify an existing chart element in the report design and to create a new chart element. The following sections contain code examples for each step in the process.

To get a chart report item from a report design, first perform the following steps using the BIRT core and model APIs, as described earlier in this book:

Next, retrieve a Chart object from the chart item. This Chart object supports accessing the BIRT Chart Engine classes and using BIRT’s charting API.

Listing 6‑15 illustrates the process of getting a chart report item. This code assumes that the chart is the first report item in a list and that the list is the first report item in the report.

Before creating a new chart item in a report design, a charting application performs all the steps to start up the platform and design engine, as described in the previous section. Next, the application creates the Chart object as described earlier in this chapter. Creating a new Chart object for use in a report design is identical to creating a chart for a stand-alone application. Finally, the application creates a chart element and sets up the properties required to link the Chart object to the element by performing the following tasks. These tasks relate to the appearance and behavior of a chart inside a report design. If the chart is not deployed in a report, the tasks in this section are not required.

The following sections describe these tasks in more detail and provide code examples for every step.

Creating a chart item in a report design requires an ElementFactory object. To get an ElementFactory object, use the getElementFactory( ) method of the ReportDesignHandle object, as shown in the following line of code:

The chapter on programming with the BIRT APIs provides more information about using the Design Engine APIs and how to place a new item in a report design.

A chart’s type and subtype determine the appearance of the chart in BIRT Report Designer. In conjunction with sample data, these properties provide a realistic rendering of the chart item in the report design’s layout window and in the chart wizard. To ensure that the appearance of this rendered chart is as accurate as possible, set the chart’s type so that it matches the series type set on the axis. Many types, such as bar, Gantt, line, and stock, are available for a chart with axes. Charts without axes can be dial, pie, or radar types only.

The bubble, dial, difference, Gantt, and pie classes each support only a single type. The other chart types have multiple subtypes. Set the chart type and subtype by using the Chart methods setType( ) and setSubType( ) respectively. These methods take a single String argument. Table 6-1 shows the available values for chart types and the valid subtypes for each chart type. Because cone, pyramid, and tube charts are merely different representations of a bar chart, they have the same subtypes as a bar chart.

Listing 6‑16 shows how to set a chart type and subtype.

This section describes an optional step in the creation of a chart. Sample data provides visual information in BIRT Report Designer about a chart’s appearance. If you omit the code in Listing 6‑17, the chart renders correctly when the report generates, but the designer’s layout window does not display sample values.

A chart report item extends from the design engine’s ReportItemHandle class by further extending the ExtendedItemHandle class. Use the ElementFactory object to create this object by using the newExtendedItem( ) method of the ElementFactory object, as shown in the following line of code:

Set the chart.instance property of the report item object to contain the chart instance object. Get the report item from the extended item handle object, as shown in Listing 6‑18.

The new chart item still does not have access to data from the report design. The chart item uses data rows from a data set and column bindings that define how to apply values from data set columns to the chart. The names of the column bindings must match the column names used in the chart’s series objects.

To access a data set, create a data set or get an existing data set from the report design. Next, set up the columns to bind to the chart by instantiating org.eclipse.birt.report.model.api.elements.structures.ComputedColumn objects. A ComputedColumn object contains an expression that accesses columns from a data set. The code in Listing 6‑19 gets the first data set in the report design.

Use the extended item handle to bind the chart to the data set and data columns, as shown in Listing 6‑20.

The extended report item supports all the properties provided by the org.eclipse.birt.report.model.api.ReportItemHandle class. These properties include a bookmark, dimensions, and a theme. For example, to set the dimensions of the chart report item, use code as shown in Listing 6‑21.

After setting the properties of the chart and binding the chart to data, add the new chart to the report design. Listing 6‑22 adds the chart item to the footer of an existing list item.

The report design file on disk does not yet contain the chart report item. Typically, you save the modified report design with a new name in order not to overwrite the original report design file.

The code in Listing 6‑23 uses many of the techniques illustrated in this chapter in a complete Java application that creates a chart report item.