Some properties, like dimension, are simple properties that take a single value. Some simple properties accept a restricted set of values that the class defines as static fields. Use the Javadoc to find these values.

Other properties, such as a chart’s plot or title, are complex. A getter method for a complex property returns an object. For example, the Chart.getTitle( ) method returns an org.eclipse.birt.chart.model.layout.TitleBlock object. The Chart interfaces do not provide setter methods for complex properties. When code changes the properties of a complex property, the changes take effect on the chart immediately.

Some properties, such as the horizontal spacing of elements within a plot, use values based on the current units of measurement. Call the Chart.setUnits( ) method to set the units that you prefer.

Listing 6‑3 shows how to set simple and complex properties and the units of measurement.

All charts have a plot property, which specifies the area in a Chart object that contains the chart itself. The plot is an object that implements the org.eclipse
.birt.chart.model.layout.Plot interface. Plot defines horizontal and vertical spacing and the client area, which contains the rendering of the chart. The client area is itself a complex property that defines properties such as the background color and outline of the rendered chart. Plot provides all the properties defined by the Block interface in the same package, such as the background and outline. When setting values for a property that multiple components provide, determine the best class on which to modify the property based on the characteristics of all the classes.

To set properties of the plot, first get a Plot object from the chart instance object. Then, use a setter method of a component of the Plot object. Listing 6‑4 illustrates how to get the chart plot and modify its properties.

All charts have a legend property, which is the area in a Chart object that contains the chart legend. For a chart without axes, the legend identifies the slices on a pie chart or pointers on a meter chart. For a chart with axes, the legend identifies the series that display values on the x-axis. For a chart with multiple y-series, the legend displays separate sections for each series. Typically, if there is only one x‑axis group and one y-series, do not make the legend visible.

The legend is an object that implements the org.eclipse.birt.chart.model
.layout.Legend interface, which extends the Block interface. Legend provides all the Block properties, plus properties specific to Legend, such as position, title, text, and values. The default position of the legend is to the right of the plot area. Within this position, change the location of the legend by setting its anchor property.

To set properties of the chart legend, first get a Legend object from the chart instance object. Then, use a setter method of a component of the Legend object. To set properties of legend lines, use a LineAttribute object from the Legend object. Listing 6‑5 illustrates how to get the chart legend and modify its properties.

A chart with axes always has at least two axes, the primary base axis and the axis orthogonal to the base axis. A primary base axis is a category axis, which displays values of any data type and is typically an x-axis. A chart can have more than one primary base axis. Every base axis has at least one axis that is orthogonal to it. An orthogonal axis is a value axis, which displays numeric values and is typically a y-axis.

The org.eclipse.birt.chart.model.component.Axis interface supports both category and value axes.

To set the properties of one or more axes of a chart, cast the Chart object to a type of ChartWithAxes, as shown in the following statement:

To access a category axis, call the ChartWithAxes.getPrimaryBaseAxes( ) method. This method returns an array. If there is only one primary base axis, get the first element of the array, as shown in the following code:

To access the value axis for a single value-axis chart, call the method, getPrimaryOrthogonalAxis( ). For a chart having multiple value axes, access the list of axes by calling getOrthogonalAxes( ).

Listing 6‑6 illustrates the technique for getting the axes of a chart and setting their properties.

All charts use series to define the data values to represent. Series objects contain a list of values to plot on the chart. To instantiate a Series object, call the static create( ) method on org.eclipse.birt.chart.model.component.impl.SeriesImpl. Define the set of values for a series either with a dynamic query that accesses an external data source or with a static data set that is a list of values. A query on the series definition object supports grouping and sorting of the data.

The series for an x-axis or for the values that control the number of sectors in a pie can contain non-numeric data values, such as dates or text values. For example, these series can contain the quarters in a range of years, or product codes or countries.

The series for a y-axis or for the values that control the size of the sectors in a pie chart must hold numeric values. These series are implementations of specific subinterfaces of the Series interface. Each chart type uses its own series type, to control the chart represents the values. For example, a BarSeries object has riser and riser outline properties to control the appearance of the bars.

Series definition objects provide access to the series objects for the chart and standard properties such as the palette of colors in which to display pie sectors, bars, and other markers. To instantiate a SeriesDefinition object, call the static org.eclipse.birt.chart.model.data.impl.SeriesDefinitionImpl.create( ) method. To add a series to a series definition, get the collection of series and add the series to that collection. To set the color of a series, get a SeriesPalette object and call its shift( ) method.

A series definition supports multiple series. The series do not all have to be the same type. For example, a line chart can use the same axes as a bar chart. Typically, a chart displays extra series on a y‑axis, not on an x-axis.

Listing 6‑7 illustrates how to get a series definition from an axis and how to change a property of the series.

To display values on a chart, add category and value series to a newly created chart or modify the series on an existing chart. For a chart with axes, associate series with both category and value axes.

On a chart with axes, the category series is the set of values that the category axis displays. On a chart without axes, the category series defines the number of sectors in a pie chart or the number of pointers on a meter chart. To create a category series, use the static create( ) method of the SeriesImpl class, as shown in the following line:

The orthogonal series specifies the representation of the values in the value series. On a chart with axes, the orthogonal series is the set of values that display on the y-axis, for example, appearing as bars, bubbles, stock bar sticks or candlesticks. On a chart without axes, the orthogonal series sets the size of slices in a pie or the position of a pointer on a meter chart. A chart can have multiple orthogonal series of the same or differing types.

The orthogonal series classes are subclasses of the SeriesImpl class, and are located in the org.eclipse.birt.chart.model.type.impl package. The following classes are available:

The BarSeriesImpl class supports bar, cone, pyramid, and tube chart types.

To create an orthogonal series, use the static create( ) method of the series class. The following line shows an example of creating a bar series:

A category series supports only the properties defined by the SeriesImpl class. A value series supports additional properties defined by the relevant subclass of SeriesImpl. For example, a bar series supports bar stacking and outlines on the risers. A pie series supports slice outlines and exploded slices.

To set the properties of a series, use getter and setter methods of the appropriate series objects, as shown in Listing 6‑8, which sets properties on BarSeries and LineSeries objects.

Create either a query or a data set, and add that object to the series data definition. To create a query, use the static create( ) method of the org.eclipse.birt.chart.model.data.impl.QueryImpl class. To create a data set, use the static create( ) method on a subclass of DataSetImpl. The data set type must match the type of values that the axis displays. For example, a category axis displaying date-and-time data values requires a data set of class DateTimeDataSet. Similarly, a bar series requires a numeric data set, of class NumberDataSet. Some series require multiple sets of data. For example, a stock series requires four sets of data, high, low, open, and close. Either add four queries in that order to the series, or add a StockDataSet to the series. Listing 6‑9 adds queries and data sets to line, bar, and stock series.

Listing 6‑10 illustrates how to create a second value series, set some of its properties, assign data to the series, and add the series to an axis.

After setting the properties of a SeriesDefinition object, add the object to the chart. For a chart without axes, add the series definitions directly to the Chart object’s collection of series definitions. The first series definition in the collection defines the category series and the second one defines the orthogonal series. For a chart with axes, add the series definition to each Axis object’s collection of series definitions as shown in Listing 6‑11.

A chart plots every value that it receives unless an org.eclipse.birt.chart
.model.data.SeriesGrouping object defines the type of aggregation to perform. Set up aggregation on the category series to define the value on which to aggregate and the type of aggregation, as shown in Listing 6‑12. The chart builder user interface displays the available aggregation types. All orthogonal series use the aggregation type specified by the category series grouping by default.

Every value series uses the same aggregation expression to aggregates values to display unless the application changes the aggregation by setting up a SeriesGrouping specific to the series. Change only the grouping properties that differ from the default grouping, as shown in Listing 6‑13.

Two kinds of chart event handlers are available to a charting application: a Java event handler or a JavaScript event handler.

To add a Java event handler, create a separate Java class file containing the event handler method or methods. The process for creating a Java event handler class is identical to the process for creating a Java event handler class for any other report item, as described in the chapters on scripting with Java and scripting for charts. The class must include a function for every event handler method of the chart.

To register a Java class in the charting application code, use the setScript( ) method of the chart instance object, as shown in the following statement:

The string argument passed to the setScript( ) method is the fully qualified name of the Java class. Do not include the .class extension in the class name.

To add a JavaScript event handler, code the script as one long string and pass that string to the setScript( ) method of the chart instance object. For example, the statement in Listing 6‑14 passes a string to chart.setScript( ) containing event handler script for the beforeDrawDataPointLabel event handler. Line breaks in the JavaScript code are indicated by backslash n ( \n ), and quotes within the script are indicated by a backslash quote ( \" ). The JavaScript code consists of several strings concatenated together to form a single string. This technique helps make the script more readable.