Documentation/DevGuide/Charts

Chart documents produce graphical representations of numeric data. They are always embedded objects inside other LibreOffice documents. The chart document is a document model similar to Writer, Calc and Draw document models, and it can be edited using this document model.

Creating Charts
The com.sun.star.table.XTableChartsSupplier interface of the com.sun.star.sheet.Spreadsheet service is used to create and insert a new chart into a Calc document. This creates a chart that uses data from the com.sun.star.chart.XChartDataArray interface of the underlying cell range. A generic way to create charts is to insert an OLE-Shape into a draw page and transform it into a chart setting a class-id.

Creating and Adding a Chart to a Spreadsheet
Charts are used in spreadsheet documents to visualize the data that they contain. A spreadsheet is one single sheet in a spreadsheet document and offers a com.sun.star.table.XTableChartsSupplier interface, that is required by the service com.sun.star.sheet.Spreadsheet. With this interface, a collection of table charts that are a container for the actual charts can be accessed. To retrieve the chart document model from a table chart object, use the method.

The following example shows how to insert a chart into a spreadsheet document and retrieve its chart document model. The example assumes that there is a com.sun.star.sheet.XSpreadsheet to insert the chart and an array of cell range addresses that contain the regions in which the data for the chart can be found. Refer to Spreadsheet Documents for more information about how to get or create these objects. The following snippet shows how to insert a chart into a Calc document.

Creating a Chart OLE Object in Draw and Impress
The alternative is to create an OLE shape and insert it into a draw page. Writer, Spreadsheet documents and Draw/Impress documents have access to a draw page. The shape is told to be a chart by setting the unique class-id.

A draw page collection is obtained from the com.sun.star.drawing.XDrawPagesSupplier of a draw or presentation document. To retrieve a single draw page, use com.sun.star.container.XIndexAccess.

A spreadsheet document is also a com.sun.star.drawing.XDrawPagesSupplier that provides draw pages for all sheets, that is, the draw page for the third sheet is obtained by calling  on the interface com.sun.star.container.XIndexAccess of the container, returned by com.sun.star.drawing.XDrawPagesSupplier:getDrawPages.

A spreadsheet draw page can be acquired directly at the corresponding sheet object. A single sheet supports the service com.sun.star.sheet.Spreadsheet that supplies a single page, com.sun.star.drawing.XDrawPageSupplier, where the page is acquired using the method.

The LibreOffice Writer currently does not support the creation of OLE Charts or Charts based on a text table in a Writer document using the API.

The document model is required once a chart is inserted. In charts inserted as OLE2Shape, the document model is available at the property  of the OLE2Shape after setting the.

The following example assumes a valid drawing document in the variable  and creates a chart in a Draw document. See Drawing Documents and Presentation Documents for an example of how to create a drawing document.

Setting the Chart Type
The default when creating a chart is a bar diagram with vertical bars. If a different chart type is required, apply a different diagram type to this initial chart. For example, to create a pie chart, insert the default bar chart and change it to a pie chart.

To change the type of a chart, create an instance of the required diagram service by its service name using the service factory provided by the com.sun.star.chart.XChartDocument. This interface is available at the chart document model. After this service instance is created, set it using the  method of the chart document.

In the following example, we change the chart type to a com.sun.star.chart.XYDiagram, also known as a scatter chart. We have assumed that there is a chart document in the variable  already. The previous sections described how to create a document.

Accessing Existing Chart Documents
To get a container of all charts contained in a spreadsheet document, use the com.sun.star.table.XTableChartsSupplier of the service com.sun.star.sheet.Spreadsheet, which is available at single spreadsheets.

To get all OLE-shapes of a draw page, use the interface com.sun.star.drawing.XDrawPage, that is based on com.sun.star.container.XIndexAccess. You can iterate over all shapes on the draw page and check their  property to find out, whether the found object is a chart.

Document Structure
The important service for charts is com.sun.star.chart.ChartDocument. The chart document contains all the top-level graphic objects, such as a legend, up to two titles called  and , an axis title object for each primary axis if the chart supports axis. The com.sun.star.chart.ChartArea always exists. This is the rectangular region covering the complete chart documents background. The important graphical object is the diagram that actually contains the visualized data.

Apart from the graphical objects, the chart document is linked to some data. The required service for the data component is com.sun.star.chart.ChartData. It is used for attaching a data change listener and querying general properties of the data source, such as the number to be interpreted as NaN ("not a number"), that is, a missing value. The derived class com.sun.star.chart.ChartDataArray allows access to the actual values. Every component providing the  service should also support.

The following diagram shows the services contained in a chart and their relationships.



The name spaces in the diagram have been omitted to improve readability. The services are all in the name space com.sun.star.chart. The interfaces in this diagram are com.sun.star.chart.XChartDocument, com.sun.star.drawing.XShape , com.sun.star.lang.XComponent , and com.sun.star.beans.XPropertySet.

The chart document model passes its elements through the interface com.sun.star.chart.XChartDocument. This interface consists of the following methods:

Data Access
Data can only be accessed for reading when a chart resides inside a spreadsheet document and was inserted as a table chart, that is, the table chart obtains its data from cell ranges of spreadsheets. To change the underlying data, modify the content of the spreadsheet cells. For OLE charts, that is, charts that were inserted as  objects, modify the data.

The data of a chart is acquired from the com.sun.star.chart.XChartDocument interface of the chart document model using the method com.sun.star.chart.XChartDocument:getData. The current implementation of LibreOffice charts provides a com.sun.star.chart.XChartDataArray interface, derived from com.sun.star.chart.XChartData and supports the service com.sun.star.chart.ChartDataArray.

The methods of  are:

Included are the following methods from :

The com.sun.star.chart.XChartDataArray interface offers several methods to access data. A sequence of sequences is obtained containing double values by calling. With, such an array of values can be applied to the.

The arrays are a nested array, not two-dimensional. Java has only nested arrays, but in Basic a nested array must be used instead of a multidimensional array. The following example shows how to apply values to a chart in Basic:

With the methods of the  interface, check if a number from the chart has to be interpreted as non-existent, that is, the number is not a number (NaN).

Additionally, the  interface is used to connect a component as a listener on data changes. For example, to use a spreadsheet as the source of the data of a chart that resides inside a presentation. It can also be used in the opposite direction: the spreadsheet could display the data from a chart that resides in a presentation document. To achieve this, the com.sun.star.table.CellRange service also points to the XChartData interface, so that a listener can be attached to update the chart OLE object.

The following class  demonstrates how to synchronize the data of a spreadsheet range with a chart residing in another document. Here the chart is placed into a drawing document.

The class  in the example below implements a com.sun.star.lang.XEventListener to get notified when the spreadsheet document or drawing document are closed.

It also implements a com.sun.star.chart.XChartDataChangeEventListener that listens for changes in the underlying. In this case, it is the range in the spreadsheet.

Chart Document Parts
In this section, the parts that most diagram types have in common are discussed. Specific chart types are discussed later.

Diagram
The diagram object is an important object of a chart document. The diagram represents the visualization of the underlying data. The diagram object is a graphic object group that lies on the same level as the titles and the legend. From the diagram, data rows and data points are obtain that are also graphic objects that represent the respective data. Several properties can be set at a diagram to influence its appearance. Note that the term data series is used instead of data rows.

Some diagrams support the service com.sun.star.chart.Dim3DDiagram that contains the property. If this is set to true, you get a three-dimensional view of the chart, which in LibreOffice is usually rendered in OpenGL. In 3-D charts, you can access the z-axis, which is not available in 2-D.

The service com.sun.star.chart.StackableDiagram offers the properties Percent and Stacked. With these properties, accumulated values can be stacked for viewing. When setting  to , all slices through the series are summed up to 100 percent, so that for an   the whole diagram space would be filled with the series. Note that setting the  property also sets the   property, because   is an addition to.

There is a third service that extends a base diagram type for displaying statistical elements called com.sun.star.chart.ChartStatistics. With this service, error indicators or a mean value line are added. The mean value line represents the mean of all values of a series. The regression curve is only available for the, because a numeric x-axis, is required.



The illustration above shows that there are eight base types of diagrams. The three services,,   and   are also supported for several diagram types and allows extensions of the base types as discussed. For instance, a three-dimensional pie chart can be created, because the com.sun.star.chart.PieDiagram service points to the com.sun.star.chart.Dim3DDiagram service.

The services com.sun.star.chart.AreaDiagram, com.sun.star.chart.LineDiagram , and com.sun.star.chart.BarDiagram support all three feature services.

Axis
All charts can have one or more axis, except for pie charts. A typical two-dimensional chart has two axis, an x- and y-axis. Secondary x- or y-axis can be added to have up to four axis. In a three-dimensional chart, there are typically three axis, x-, y- and z-axis. There are no secondary axis in 3-dimensional charts.

An axis combines two types of properties:


 * Scaling properties that affect other objects in the chart. A minimum and maximum values are set that spans the visible area for the displayed data. A step value can also be set that determines the distance between two tick-marks, and the distance between two grid-lines if grids are switched on for the corresponding axis.
 * Graphical properties that influence the visual impression. These are character properties (see com.sun.star.style.CharacterProperties ) affecting the labels and line properties (see com.sun.star.drawing.LineProperties ) that are applied to the axis line and the tick-marks.



Different diagram types support a different number of axis. In the above illustration, a com.sun.star.chart.XYDiagram, also known as a scatter diagram, is shown. The scatter diagram supports x- and y-axis, but not a z-axis as there is no 3-dimensional mode. The com.sun.star.chart.PieDiagram supports no axis at all. The com.sun.star.chart.BarDiagram supports all kinds of axis. Note that the z-Axis is only supported in a three-dimensional chart. Note that there is a com.sun.star.chart.ChartTwoAxisXSupplier that includes the com.sun.star.chart.ChartAxisXSupplier and is supported by all diagrams in LibreOffice required to support the service.

The following example shows how to obtain an axis and how to change the number format.

Data Series and Data Points
The objects that visualize the actual data are data series. The API calls them data rows that are not rows in a two-dimensional spreadsheet table, but as sets of data, because the data for a data row can reside in a column of a spreadsheet table.

The data rows contain data points. The following two methods at the com.sun.star.chart.XDiagram interface allow changes to the properties of a whole series or single data point:

The index provided in these methods is 0-based, that is, 0 is the first series. In, the first series has an index 1, because the first array of values contains the x-values of the diagram that is not visualized. This behavior exists for historical reasons.

In a spreadsheet context, the indexes for  are called   and   and are misleading. The  parameter gives the data row, that is, the series index. The  gives the index of the data point inside the series, regardless if the series is taken from rows or columns in the underlying table. To get the sixth point of the third series, write.

Data rows and data points have com.sun.star.drawing.LineProperties and com.sun.star.drawing.FillProperties. They also support com.sun.star.style.CharacterProperties for text descriptions that can be displayed next to data points.

Properties can be set for symbols and the type of descriptive text desired. With the  property, one of several predefined symbols can be set. With, a URL that points to a graphic in a format known by LibreOffice can be set that is then used as a symbol in a com.sun.star.chart.LineDiagram or com.sun.star.chart.XYDiagram.

The following example demonstrates how to set properties of a data point. Before implementing this example, create a chart document and diagram of the type.

Features of Special Chart Types
Examples of some of the services that are not available for all chart types are discussed in this section. Only examples that can be changed in specific chart types only are discussed.

Statistics
Statistical properties like error indicators or regression curves can be applied. The regression curves can only be used for xy-diagrams that have tuples of values for each data point. The following example shows how to add a linear regression curve to an xy-diagram.

Additionally, the mean value line is displayed and error indicators for the standard deviation are applied.

3-D Charts
Some chart types can display a 3-dimensional representation. To switch a chart to 3-dimensional, set the boolean property  of the service com.sun.star.chart.Dim3DDiagram.

In addition to this property, bar charts support a property called  (see service com.sun.star.chart.BarDiagram ) that arranges the series of a bar chart along the z-axis, which in a chart, points away from the spectator. The service com.sun.star.chart.Chart3DBarProperties offers a property  to set the style of the data point solids. The solid styles can be selected from cuboids, cylinders, cones, and pyramids with a square base (see constants in com.sun.star.chart.ChartSolidType ).

The  of a 3-dimensional chart is also a scene object that supports modification of the rotation and light sources. The example below shows how to rotate the scene object and add another light source.

Refer to Drawing Documents and Presentation Documents for additional details about three-dimensional properties.

Pie Charts
Pie charts support the offset of pie segments with the service com.sun.star.chart.ChartPieSegmentProperties that has a property  to drag pie slices radially from the center up to an amount equal to the radius of the pie. This property reflects a percentage, that is, values can go from 0 to 100.

Note that the  property is not available for donut charts and three-dimensional pie charts.

Stock Charts
A special data structure must be provided when creating stock charts. When a com.sun.star.chart.StockDiagram is set as the current chart type, the data is interpreted in a specific manner depending on the properties  and. The following table shows what semantics are used for the data series.

For example, if the property  is set to   and   to , the first series is interpreted as the value of the stock when the stock exchange opened, and the fourth series represents the value when the stock exchange closed. The lowest and highest value during the day is represented in series two and three, respectively.

Chart Document Controller
The chart document model implements com.sun.star.frame.XModel. Therefore, controllers can be registered with the method. When one of the registered controllers is set as current one with, this one is also returned in the method.

Apart from using the controller directly, there are three other useful methods:

With a call to  all registered controllers will no longer be notified about changes in the model. If there are changes those are notified no earlier than after calling. This is especially useful if you do many changes to the chart model at a time but do not need the view to be updated after every single change. The method  just gives you the state whether controllers are locked or not.

Chart Add-Ins
Chart types can also be created by developing components that serve as chart types. Existing chart types can be extended by adding additional shapes or modifying the existing shapes. Alternatively, a chart can be created from scratch. If drawing from scratch, it is an empty canvas and all shapes would have to be drawn from scratch.

Chart Add-Ins are actually UNO components, thus, you should be familiar with the chapter Writing UNO Components.

Prerequisites
The following interfaces must be supported for a component to serve as a chart add-in:


 * com.sun.star.lang.XInitialization
 * com.sun.star.util.XRefreshable
 * com.sun.star.lang.XServiceName
 * com.sun.star.lang.XServiceInfo
 * com.sun.star.lang.XTypeProvider to access the add-in interfaces from LibreOffice Basic and other interpreted programming languages (optional).

In addition to these interfaces, the following services must be supported and returned in the  method of com.sun.star.lang.XServiceInfo ):


 * com.sun.star.chart.Diagram
 * A unique service name that identifies the component. This service name has to be returned in the  method of com.sun.star.lang.XServiceName.

How Add-Ins Work
The method  from the com.sun.star.lang.XInitialization interface is the first method that is called for an add-in. It is called directly after it is created by the com.sun.star.lang.XMultiServiceFactory provided by the chart document. This method gets the  object.

When  is called, the argument returned is the chart document. Store this as a member to that it can be called later in the  call to access all elements of the chart. The following is an example for the  method of an add-in written in Java:

An important method of an add-in component is  from the com.sun.star.util.XRefreshable. This method is called every time the chart is rebuilt. A change of data results in a refresh, but also a resizing or changing of a property that affects the layout calls the  method. For example, the property  that switches the legend on and off.

To add shapes to the chart, create them once and modify them later during the refresh calls. In the following example, a line is created in  and modified during  :

The subroutine  is a helper to determine the position of a point inside the diagram coordinates. This add-in calculates the maximum and minimum values for each slice of data points, and creates two polygons based on these points.

How to Apply an Add-In to a Chart Document
There is no method to set an add-in as a chart type for an existing chart in the graphical user interface. To set the chart type, use an API script, for instance, in LibreOffice Basic. The following example sets the add-in with service name “ ” at the current document. To avoid problems, it is advisable to create a chart that has the same type as the one that the add-in sets as  type.