Using the simplified charting API
BIRT provides a simplified API for manipulating chart properties. In earlier versions, accessing the chart model was less straightforward and the differences between the chart model and the report model often led to confusion. The simplified charting API integrates the chart model with the report model script API, and uses an interface that is more like the API for other report items.
Listing 39‑23 shows how earlier versions of BIRT set color by category.
Listing 39‑23 Setting color by category in earlier versions of BIRT
public void beforeGeneration( Chart cm, IChartScriptContext icsc )
{
cm.getLegend( ).setItemType(LegendItemType.CATEGORIES_LITERAL);
}
Listing 39‑24 shows how to implement the same functionality using the simplified charting API in the beforeFactory event handler for a report that contains a chart named Chart1.
Listing 39‑24 Setting color by category using the simplified charting API
var chart1 = this.getReportElement( "Chart1" )
chart1.setColorByCategory( true );
A typical use for the simplified charting API is to modify an existing chart in a report design. In addition, a Java application uses the simplified charting API to modify the chart’s content.
Getting an instance of a chart item
The key component of the simplified charting API is the IChart interface. Like the other report item interfaces, IChart extends IReportItem. Because of the more complex nature of the chart item, the IChart interface is in a different package and has a more extensive set of methods than the other report item interfaces. To obtain an IChart instance, use the name of the chart element as the argument to the getReportElement( ) method.
Use the following code to get an IChart object in a Java application using the Design Engine API or when developing a Java event handler:
IChart chart = (IChart)rptdesign.getReportElement( "Chart1" );
In a JavaScript event handler, use the following code to get the IChart object:
var chart1 = this.getReportElement( "Chart1" )
Understanding the sub-interfaces of IChart
There are two sub-interfaces of IChart:
*IChartWithAxes
*IChartWithoutAxes
IChartWithoutAxes adds only one method to IChart. IChartWithAxes adds several methods. Typically, in a Java application, cast the chart element to an appropriate sub-interface, as shown in the following code:
IChartWithAxes chart = ( IChartWithAxes )
rptdesign.getReportElement("Name of an Axis-containing Chart");
Table 39-8 lists the methods of the IChart interface.
Table 39-8 IChart methods
Method
Action
getCategory( )
Returns an ICategory instance containing the category. This object supports changing settings, such as grouping and sorting for a chart category.
getDescription( )
Returns an IText instance containing the chart description. Supports changing the description.
getDimension( )
Gets the current dimension setting.
getFactory( )
Returns an IComponentFactory instance used to create chart elements.
getLegend( )
Returns an ILegend instance containing the legend.
getOutputType( )
Returns a String containing the output type.
getTitle( )
Returns an IText instance containing the chart title. Supports changing the title.
isColorByCategory( )
Returns the color-by-category setting.
setColorByCategory( boolean flag )
Indicates whether to set the color by category.
setDimension( String type )
Sets the dimension for the chart:
*TwoDimensional
*TwoDimensionalWithDepth
*ThreeDimensional
setOutputType( String type )
Sets the output type to one of the following formats:
*PNG
*SVG
*JPG
*BMP
Table 39-9 lists the methods of the IChartWithAxes interfaces.
Table 39-9 IChartWithAxes methods
Method
Action
getCategoryAxis( )
Returns an IAxis instance containing the category axis.
getValueAxes( )
Returns an array of IAxis instances containing the set of value axes.
getValueSeries( )
Returns a two dimensional array of IValueSeries instances containing the value series.
isHorizontal( )
Returns a boolean value indicating whether the chart orientation is horizontal.
setHorizontal( boolean flag )
Sets the orientation of the chart to horizontal when true or vertical when false.
Table 39-10 describes the method of the IChartWithoutAxes interfaces.
Table 39-10 IChartWithout Axes method
Method
Action
getValueSeries( )
Returns a one-dimensional array of IValueSeries instance containing the value series.
The most typical use of the API is in a beforeFactory event handler, which the report engine calls prior to generating the report. This event handler also supports modifying the design of the report. Listing 39‑25 uses script in the report’s beforeFactory event handler to locate a chart named Chart1, set the chart title to the string, My New Title, and render the title in red.
Listing 39‑25 Using the beforeFactory event handler
var chart1 = this.getReportElement( "Chart1" );
var color1 = chart1.getTitle().getCaption().getColor();
 
chart1.setColorByCategory( true );
chart1.getTitle().getCaption().setValue( "My New Title" );
 
color1.setRed( 255 );
color1.setGreen( 0 );
color1.setBlue( 0 );
chart1.getTitle( ).getCaption( ).setColor( color1 );
Adding the following line to the script changes the chart to a three‑dimensional chart:
chart1.setDimension( "ThreeDimensional" );
The following line of script sets the output type of the chart to PNG:
chart1.setOutputType( "PNG" );
Because IChart extends ReportItem, you can set chart dimensions by using the setWidth( ) and setHeight( ) methods. For example, to set the width and height to six inches, use the following script:
chart1.setWidth( "6in" );
chart1.setHeight("6in");