Understanding the chart script context
All chart event handler methods for both Java and JavaScript receive a chart script context, which is a ChartScriptContext object, as a parameter. The chart script context object provides access to the following objects:
*Chart instance
*Locale
*ULocale
*Logging
*External context
Table 39-2 lists the methods of the chart script context object and their actions.
Table 39-2 Chart script context methods
Method
Action
getChartInstance( )
Returns the Chart instance object.
getExternalContext( )
Returns the IExternalContext object that provides access to an external scriptable object. The user application defines the external scriptable object.
getLocale( )
Returns the Locale object for the current locale.
getLogger( )
Returns the Logger object for use in logging messages and errors.
getULocale( )
Returns the ULocale object for the current locale.
setChartInstance( Chart )
Sets the Chart instance.
setExternalContext( IExternalContext )
Sets the external context.
setLogger( ILogger )
Sets the logger.
setULocale( ULocale )
Sets the ULocale.
Using the Chart instance
The chart script context object provides access to a Chart instance object. The Chart instance has methods to access, change, and test chart properties.
Chart instance getter methods
The Chart instance getter methods provide the current values of a chart’s properties. Table 39-3 lists the Chart instance getter methods and returned property values.
Table 39-3 Chart instance getter methods
Method
Property value returned
getBlock( )
The Block containment reference
getDescription( )
The Description containment reference
getDimension( )
The Dimension attribute
getExtendedProperties( )
The Extended Properties containment reference list
getGridColumnCount( )
The Grid Column Count attribute
getInteractivity( )
The Interactivity containment reference
getLegend( )
Legend block
getPlot( )
Plot block
getSampleData( )
The Sample Data containment reference
getScript( )
The Script attribute
getSeriesForLegend( )
Array of series containing captions or markers that render in the legend
getSeriesThickness( )
The Series Thickness attribute
getStyles( )
The Styles containment reference list
getSubType( )
The Sub Type attribute
getTitle( )
Title block for the chart
getType( )
The Type attribute
getUnits( )
The Units attribute
getVersion( )
The Version attribute
Chart instance setter methods
The Chart instance setter methods support setting the values of various chart properties. Table 39-4 lists the Chart instance setter methods and the values set by these methods.
Table 39-4 Chart instance setter methods
Method
Property value set
setBlock( Block value )
The Block containment reference
setDescription( Text value )
The Description containment reference
setDimension ( ChartDimension value )
The Dimension attribute
setGridColumnCount( int value )
The Grid Column Count attribute
setInteractivity( Interactivity value )
The Interactivity containment reference
setSampleData( )
The Sample Data containment reference
setScript( )
The Script attribute
setSeriesThickness( )
The Series Thickness attribute
setSubType( )
The Sub Type attribute
setType( )
The Type attribute
setUnits( )
The Units attribute
setVersion( )
The Version attribute
Chart instance methods
Use Chart instance methods if the simple charting API is not sufficient for your requirements. Table 39-5 provides examples of Chart instance methods and describes the action performed by each method.
Table 39-5 Miscellaneous Chart instance methods 
Method
Action
clearSections( int iSectionType )
Walks through the model and clears sections of the specified type
createSampleRuntimeSeries( )
Builds run-time series instances for each design‑time series based on the sample data contained in the model
setDimension( ChartDimension value )
Sets the value of the Dimension attribute
unsetDimension( )
Unsets the value of the Dimension attribute
unsetGridColumn( )
Unsets the value of the Grid_Column_Count attribute
unsetSeriesThickness( )
Unsets the value of the Series_Thickness attribute
unsetVersion( )
Unsets the value of the Version attribute
Accessing the Chart instance in an event handler
Most event handlers use the chart script context to access the Chart instance. The beforeGeneration event, which occurs after the data set events and just before creating the chart, provides direct access to the Chart instance.
The JavaScript example in Listing 39‑1 contains a beforeGeneration event handler that sets the unit spacing for the entire chart. The beforeDrawSeries event handler uses the chart context to retrieve the Chart instance and set the unit spacing for one series, having a title, series one. Running this script for a chart containing a two-bar series makes one bar series wider than the other. afterDrawSeries resets the unit spacing for the series. Only a ChartWithAxes instance, which extends the Chart object, supports setUnitSpacing.
Listing 39‑1 Setting unit spacing in the beforeGeneration event handler
function beforeGeneration( chart, context )
{
chart.setUnitSpacing( 20 );
}
 
var oldSpacing;
function beforeDrawSeries( series, seriesRenderer, context )
{
oldSpacing = context.getChartInstance().getUnitSpacing( );
if ( series.getSeriesIdentifier( ) == "series one" ) {
context.getChartInstance( ).setUnitSpacing( 70 );
}
}
function afterDrawSeries( series, seriesRenderer, context )
{
context.getChartInstance( ).setUnitSpacing( oldSpacing );
}
Understanding the external context
When running from a report, the chart engine uses the report’s reportContext object to access its external context. Retrieving the external context from JavaScript uses a different method from Java. To get the external context in a chart event handler written in JavaScript, use the context.getExternalContext( ).getScriptable( ) method. In a Java-based chart event handler, use context.getExternalContext( ).getObject( ).
An event handler can access the variables and methods of the external context object. For example, set the chart axis title to a report parameter using a JavaScript event handler, as shown in Listing 39‑2, or a Java event handler, as shown in Listing 39‑3. Writing Java event handlers for charts is covered in more detail later in this chapter.
Listing 39‑2 Setting the chart axis title using a JavaScript event handler
function beforeDrawAxisTitle ( axis, title, context )
{
importPackage(
Packages.org.eclipse.birt.chart.model.attribute );
if ( axis.getType( ) == AxisType.LINEAR_LITERAL ) {
title.getCaption( ).setValue
( context.getExternalContext( ).getScriptable( )
.getParameterValue( "chartTitle" ) );
}
}
Listing 39‑3 Setting the chart axis title using a Java event handler
public void beforeDrawAxisTitle( Axis axis, Label label,
IChartScriptContext icsc )
{
IReportContext rc = ( IReportContext )
icsc.getExternalContext( ).getObject( );
String mytitle =
( String )rc.getParameterValue( "chartTitle" );
if ( axis.getType( ) == AxisType.TEXT_LITERAL ) {
label.getCaption().setValue(mytitle);
}
}