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 5-2 lists the methods of the chart script context object and their actions.
Table 5-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 5-3 lists the Chart instance getter methods and returned property values.
Table 5-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 5-4 lists the Chart instance setter methods and the values set by these methods.
Table 5-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 5-5 provides examples of Chart instance methods and describes the action performed by each method.
Table 5-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 5‑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 5‑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 5‑2, or a Java event handler, as shown in
Listing 5‑3. Writing Java event handlers for charts is covered in more detail later in this chapter.
Listing 5‑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 5‑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);
}
}