Chapter 9 Diagrams (Charts)

StarOffice can display data as a diagram, which creates graphical links between data in the form of bars, pie charts, lines or other elements. Data can either be displayed as 2D or 3D graphics, and the appearance of the diagram elements can be individually adapted in a similar way to the process used for drawing elements.

If the data is available in the form of a spreadsheet, then this can be dynamically linked to the diagram. Any modifications made to the basic data can in this instance be seen immediately in the assigned diagram. This chapter provides an overview of the programming interface for diagram modules of StarOffice and focuses on the use of diagrams within spreadsheet documents.

Using Diagrams in Spreadsheets

Diagrams are not treated as independent documents in StarOffice, but as objects that are embedded in an existing document.

While diagrams in text and drawing documents remain isolated from the content of the document, when used in spreadsheet documents, a mechanism is provided which allows a link to be established between the document data and embedded diagrams. The following example explains the interaction between spreadsheet document and diagram:

Dim Doc As Object
Dim Charts As Object
Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

Doc = StarDesktop.CurrentComponent
Charts = Doc.Sheets(0).Charts

Rect.X = 8000
Rect.Y = 1000
Rect.Width = 10000
Rect.Height = 7000

RangeAddress(0).Sheet = 0
RangeAddress(0).StartColumn = 0 
RangeAddress(0).StartRow = 0
RangeAddress(0).EndColumn = 2
RangeAddress(0).EndRow = 12

Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)

Although the code used in the example may appear to be complex, the central processes are limited to three lines: the first central line creates the Doc document variable, which references the current spreadsheet document (Doc line = StarDesktop.CurrentComponent). The code used in the example then creates a list containing all charts of the first spreadsheet (Charts line = Doc.Sheets(0).Charts). Finally, a new chart is added to the last line of this list using the addNewByName method. This new chart is then visible to the user.

The last line initializes the Rect and RangeAddress auxiliary structures, which the addNewByName method also provides as a parameter. Rect determines the position of the chart within the spreadsheet. RangeAddress determines the range whose data is to be linked to the chart.

The previous example creates a bar diagram. If a different type of graphic is needed, then the bar diagram must be explicitly replaced:

Chart = Charts.getByName("MyChart").embeddedObject
Chart.Diagram = Chart.createInstance("com.sun.star.chart.LineDiagram")

The first lines defines the corresponding chart object. The second line replaces the current diagram with a new one — in this example, a line diagram.

---

Note –

In Excel, a distinction is made between charts which have been inserted as a separate page in an Excel document and charts which are embedded in a table page. Correspondingly, two different access methods are defined there for charts. This distinction is not made in StarOffice Basic, because charts in StarOffice Calc are always created as embedded objects of a table page. The charts are always accessed using the Charts list of the associated Sheet object.

---

The Structure of Diagrams

The structure of a diagram — and therefore the list of services and interfaces supported by it — depends on its type. The methods and properties of the Z-axis, are, for example, only available in 3D diagrams, but not in 2D diagrams. In pie charts, there are no interfaces for working with axes.

The Individual Elements of a Diagram

Title, Sub-title and Key

A title, sub-title and key form part of the basic elements of every diagram. Diagrams provide their own objects for each of these elements. The Chart object provides the following properties for administrating these elements:

• HasMainTitle (Boolean) – activates the title.

• Title (Object) – object with detailed information about the diagram title (supports the com.sun.star.chart.ChartTitle service).

• HasSubTitle(Boolean) – activates the sub-title.

• Subtitle (Object) – object with detailed information about the diagram sub-title (supports the com.sun.star.chart.ChartTitle service).

• HasLegend (Boolean) – activates the key.

• Legend (Object) – object with detailed information about the key to the diagram (supports the com.sun.star.chart.ChartLegendPosition service).

In many respects, the elements specified correspond to a drawing element. This is due to the fact that both the com.sun.star.chart.ChartTitle service and the com.sun.star.chart.ChartLegendPosition support the com.sun.star.drawing.Shape service, which forms the technical program basis for drawing elements.

Users therefore have the opportunity to determine the position and size of the element using the Size and Position properties.

The other fill and line properties (com.sun.star.drawing.FillProperties and com.sun.star.drawing.LineStyle services) as well as the character properties (com.sun.star.style.CharacterProperties service) are provided for formatting the elements.

com.sun.star.chart.ChartTitle contains not only the named format properties, but also two other properties:

• TextRotation (Long) – angle of rotation of text in 100ths of a degree.

• String (String) – text which to be displayed as the title or sub-title.

The diagram key (com.sun.star.chart.ChartLegend service) contains the following additional property:

• Alignment (Enum) – position at which the key appears (default value in accordance with com.sun.star.chart.ChartLegendPosition ).

The following example creates a diagram and assigns it the title "Test", the sub-title "Test 2" and a key. The key has a gray background color, is placed at the bottom of the diagram, and has a character size of 7 points.

Dim Doc As Object
Dim Charts As Object
Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

Rect.X = 8000
Rect.Y = 1000
Rect.Width = 10000
Rect.Height = 7000

RangeAddress(0).Sheet = 0
RangeAddress(0).StartColumn = 0 
RangeAddress(0).StartRow = 0
RangeAddress(0).EndColumn = 2
RangeAddress(0).EndRow = 12

Doc = StarDesktop.CurrentComponent
Charts = Doc.Sheets(0).Charts
Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)
Chart = Charts.getByName("MyChart").EmbeddedObject

Chart.HasMainTitle = True
Chart.Title.String = "Test"

Chart.HasSubTitle = True
Chart.Subtitle.String = "Test 2"

Chart.HasLegend = True 
Chart.Legend.Alignment = com.sun.star.chart.ChartLegendPosition.BOTTOM
Chart.Legend.FillStyle = com.sun.star.drawing.FillStyle.SOLID
Chart.Legend.FillColor = RGB(210, 210, 210)
Chart.Legend.CharHeight = 7

Background

Every diagram has a background area. Every area has an object, which can be accessed using the following properties of the diagram object:

• Area (Object) – background area of the diagram (supports com.sun.star.chart.ChartArea service).

The background of a diagram covers its complete area, including the area under the title, sub-title and diagram key. The associated com.sun.star.chart.ChartArea service supports line and fill properties and provides no more extensive properties.

Diagram Walls and Floors

Although the diagram background covers the entire area of the diagram, the diagram back wall is limited to the area directly behind the data area.

Two diagram walls usually exist for 3D diagrams: one behind the data area and one as the left-hand demarcation to the Y-axis. 3D diagrams usually also have a floor.

• Floor (Object) - floor panel of the diagram (only for 3D diagrams, supports com.sun.star.chart.ChartArea service).

• Wall (Object) - diagram walls (only for 3D diagrams, supports com.sun.star.chart.ChartArea service).

The specified objects support the com.sun.star.chart.ChartArea service, which in turn provides the usual fill and line properties (com.sun.star.drawing.FillProperties and com.sun.star.drawing.LineStyle services, refer to Chapter 8, Drawings and Presentations).

The diagram walls and floor are accessed through the Chart object, which in turn is part of the Chart object:

Chart.Area.FillBitmapName = "Sky"   

The following example shows how graphics (named Sky) already contained in StarOffice can be used as a background to a diagram.

Dim Doc As Object
Dim Charts As Object
Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

Rect.X = 8000
Rect.Y = 1000
Rect.Width = 10000
Rect.Height = 7000

RangeAddress(0).Sheet = 0
RangeAddress(0).StartColumn = 0 
RangeAddress(0).StartRow = 0
RangeAddress(0).EndColumn = 2
RangeAddress(0).EndRow = 12

Doc = StarDesktop.CurrentComponent
Charts = Doc.Sheets(0).Charts

Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)
Chart = Charts.getByName("MyChart").EmbeddedObject

Chart.Area.FillStyle = com.sun.star.drawing.FillStyle.BITMAP
Chart.Area.FillBitmapName = "Sky"
Chart.Area.FillBitmapMode = com.sun.star.drawing.BitmapMode.REPEAT

Axes

StarOffice recognizes five different axes that can be used in a diagram. In the simplest scenario, these are the X and Y-axes. When working with 3D diagrams, a Z-axis is also sometimes provided. For diagrams in which the values of the various rows of data deviate significantly from one another, StarOffice provides a second X and Y-axis for second scaling operations.

First X, Y and Z-Axis

In addition to the actual axis, for each of the first X, Y, and Z-axes there can also be a title, a description, a grid, and an auxiliary grid. There is an option for displaying and concealing all of these elements. The diagram object provides the following properties for administration of these features (taking the example of a X-axis; properties for Y and Z-axis are structured in the same way):

• HasXAxis (Boolean) – activates the X-axis.

• XAxis (Object) – object with detailed information about the X-axis (supports com.sun.star.chart.ChartAxis service).

• HasXAxisDescription (Boolean) – activates description for the X-axis.

• HasXAxisGrid (Boolean) – activates main grid for X-axis.

• XMainGrid (Object) – object with detailed information about main grid for X-axis (supports com.sun.star.chart.ChartGrid service).

• HasXAxisHelpGrid (Boolean) – activates auxiliary grid for X-axis.

• XHelpGrid (Object) – object with detailed information about auxiliary grid for X-axis (supports com.sun.star.chart.ChartGrid service).

• HasXAxisTitle (Boolean) – activates title of X-axis.

• XAxisTitle (Object) – object with detailed information about title of X-axis (supports com.sun.star.chart.ChartTitle service).

Second X and Y-Axis

The following properties are available for the second X and Y-axes (properties taking example of the second X-axis):

• HasSecondaryXAxis (Boolean) – activates the second X-axis.

• SecondaryXAxis (Object) – object with detailed information about the second X-axis (supports com.sun.star.chart.ChartAxis service).

• HasSecondaryXAxisDescription (Boolean) – activates description of X-axis.

Properties of the Axes

The axis objects of a StarOffice diagram support the com.sun.star.chart.ChartAxis service. In addition to the properties for characters (com.sun.star.style.CharacterProperties service, refer to Chapter 6, Text Documents) and lines (com.sun.star.drawing.LineStyle service, refer to Chapter 8, Drawings and Presentations), it provides the following properties:

• Max (Double) - maximum value for axis.

• Min (Double) - minimum value for axis.

• Origin (Double) - point of intersect for crossing axes.

• StepMain (Double) - distance between two primary lines of the axis.

• StepHelp (Double) - distance between two secondary lines of the axis.

• AutoMax (Boolean) - automatically determines maximum value for axis.

• AutoMin (Boolean) - automatically determines minimum value for axis.

• AutoOrigin (Boolean) - automatically determines point of intersect for crossing axes.

• AutoStepMain (Boolean) - automatically determines distance between primary lines of an axis.

• AutoStepHelp (Boolean) - automatically determines distance between secondary lines of an axis.

• Logarithmic (Boolean) - scales the axes in logarithmic manner (rather than linear manner).

• DisplayLabels (Boolean) - activates the text label for axes.

• TextRotation (Long) - angle of rotation of text label of axes in 100ths of a degree.

• Marks (Const) - constant that specifies whether the primary lines of the axis should be inside or outside the diagram area (default values in accordance with com.sun.star.chart.ChartAxisMarks )

• HelpMarks (Const) - constant that specifies whether the secondary lines of the axis should be inside and/or outside the diagram area (default values in accordance with com.sun.star.chart.ChartAxisMarks )

• Overlap (Long) - percentage which specifies the extent to which the bars of different sets of data may overlap (at 100%, the bars are shown as completely overlapping, at -100%, there is a distance of the width of one bar between them).

• GapWidth (long) - percentage which specifies the distance there may be between the different groups of bars of a chart (at 100%, there is a distance corresponding to the width of one bar).

• ArrangeOrder (enum) - details of position of inscription; in addition to positioning on a line, there is also the option of splitting the label alternately over two lines (default value according to com.sun.star.chart.ChartAxisArrangeOrderType)

• TextBreak (Boolean) - permits line breaks.

• TextCanOverlap (Boolean) - permits text overlaps.

• NumberFormat (Long) - number format (refer to Number, Date and Text Format section)

Properties of the axis grid

The object for the axis grid is based on the com.sun.star.chart.ChartGrid service, which in turn supports the line properties of the com.sun.star.drawing.LineStyle support service (refer to Chapter 8, Drawings and Presentations).

Properties of the axis title

The objects for formatting the axis title are based on the com.sun.star.chart.ChartTitle service, which is also used for diagram titles.

Example

The following example creates a line diagram. The color for the rear wall of the diagram is set to white. Both the X and Y-axes have a gray auxiliary grid for visual orientation. The minimum value of the Y-axis is fixed to 0 and the maximum value is fixed to 100 so that the resolution of the diagram is retained even if the values are changed.

Dim Doc As Object
Dim Charts As Object
Dim Chart as Object

Dim Rect As New com.sun.star.awt.Rectangle
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress

Doc = StarDesktop.CurrentComponent
Charts = Doc.Sheets(0).Charts

Rect.X = 8000
Rect.Y = 1000
Rect.Width = 10000
Rect.Height = 7000

RangeAddress(0).Sheet = 0
RangeAddress(0).StartColumn = 0 
RangeAddress(0).StartRow = 0
RangeAddress(0).EndColumn = 2
RangeAddress(0).EndRow = 12

Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)

Chart = Charts.getByName("MyChart").embeddedObject
Chart.Diagram = Chart.createInstance("com.sun.star.chart.LineDiagram")

Chart.Diagram.Wall.FillColor = RGB(255, 255, 255)

Chart.Diagram.HasXAxisGrid = True
Chart.Diagram.XMainGrid.LineColor = RGB(192, 192, 192)

Chart.Diagram.HasYAxisGrid = True
Chart.Diagram.YMainGrid.LineColor = RGB(192, 192, 192)

Chart.Diagram.YAxis.Min = 0 
Chart.Diagram.YAxis.Max = 100

3D Diagrams

Most diagrams in StarOffice can also be displayed with 3D graphics. All diagram types that provide this option support the com.sun.star.chart.Dim3DDiagram. service. The service provides just one property:

• Dim3D (Boolean) – activates 3D display.

Stacked Diagrams

Stacked diagrams are diagrams that are arranged with several individual values on top of one another to produce a total value. This view shows not only the individual values, but also an overview of all the values.

In StarOffice, various types of diagrams can be displayed in a stacked form. All of these diagrams support the com.sun.star.chart.StackableDiagram service, which in turn provides the following properties:

• Stacked (Boolean) – activates the stacked viewing mode.

• Percent (Boolean) – rather than absolute values, displays their percentage distribution.

Diagram Types

Line Diagrams

Line diagrams (Service com.sun.star.chart.LineDiagram) support one X-axis, two Y-axes and one Z-axis. They can be displayed as 2D or 3D graphics (com.sun.star.chart.Dim3Ddiagram service). The lines can be stacked (com.sun.star.chart.StackableDiagram).

Line diagrams provide the following properties:

• SymbolType (const) - symbol for displaying the data points (constant in accordance with com.sun.star.chart.ChartSymbolType ).

• SymbolSize (Long) - size of symbol for displaying the data points in 100ths of a millimeter.

• SymbolBitmapURL (String) - file name of graphics for displaying the data points.

• Lines (Boolean) - links the data points by means of lines.

• SplineType (Long) - spline function for smoothing the lines (0: no spline function, 1: cubic splines, 2: B splines).

• SplineOrder (Long) - polynomial weight for splines (only for B splines).

• SplineResolution (Long) - number of support points for spline calculation.

Area Diagrams

Area diagrams (com.sun.star.chart.AreaDiagram service) support one X-axis, two Y-axes and one Z-axis. They can be displayed as 2D or 3D graphics (com.sun.star.chart.Dim3Ddiagram service). The areas can be stacked (com.sun.star.chart.StackableDiagram).

Bar Diagrams

Bar diagrams (Service com.sun.star.chart.BarDiagram) support one X-axis, two Y-axes and one Z-axis. They can be displayed as 2D or 3D graphics (com.sun.star.chart.Dim3Ddiagram service). The bars can be stacked (com.sun.star.chart.StackableDiagram).

They provide the following properties:

• Vertical (Boolean) — displays the bars vertically, otherwise they are depicted horizontally.

• Deep (Boolean) - in 3D viewing mode, positions the bars behind one another rather than next to one another.

• StackedBarsConnected (Boolean) - links the associated bars in a stacked diagram by means of lines (only available with horizontal charts).

• NumberOfLines (Long) - number of lines to be displayed in a stacked diagram as lines rather than bars.

Pie Diagrams

Pie diagrams (com.sun.star.chart.PieDiagram service) do not contain any axes and cannot be stacked. They can be displayed as 2D or 3D graphics (com.sun.star.chart.Dim3Ddiagram service).