Difference between revisions of "Documentation/BASIC Guide/Structure of Charts"

Revision as of 14:30, 18 July 2008

Using Charts in Spreadsheets
The Structure of Charts
Chart Types

Databases

Dialogs

Forms

The structure of a chart — and therefore the list of services and interfaces supported by it — depends on the chart type. For example, the methods and properties of the Z-axis, are only available in 3D charts, but not in 2D charts. And in pie charts, there are no interfaces for working with axes. The following list provides an overview about some chart elements.

The Individual Elements of a Chart

Title, Subtitle and Legend

Title, subtitle and legend are basic elements provided for every chart. The Chart object provides the following properties for administrating these elements:

HasMainTitle (Boolean): activates the title.
Title (Object): object with detailed information about the chart title (supports the com.sun.star.chart.ChartTitle service).
HasSubTitle(Boolean): activates the subtitle.
Subtitle (Object): object with detailed information about the chart subtitle (supports the com.sun.star.chart.ChartTitle service).
HasLegend (Boolean): activates the legend.
Legend (Object): object with detailed information about the legend (supports the com.sun.star.chart.ChartLegend service).

Both services com.sun.star.chart.ChartTitle and com.sun.star.chart.ChartLegend do support the service com.sun.star.drawing.Shape. This allows to determine the position and size of the elements using the Position and Size properties. As the size of the legend and the titles is calculated automatically based on the current content and the character height for example, the size property provides read access only.

Fill and line properties (com.sun.star.drawing.FillProperties and com.sun.star.drawing.LineProperties services) as well as the character properties (com.sun.star.style.CharacterProperties service) are provided for further formatting of the elements.

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

String (String): text which to be displayed as the title or subtitle.
TextRotation (Long): angle of rotation of text in 100ths of a degree.

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

Alignment (Enum): position at which the legend appears (value of type com.sun.star.chart.ChartLegendPosition ).

The following example creates a chart with a title "Main Title String", a subtitle "Subtitle String" and a legend. The legend has a gray background color, is placed at the bottom of the chart, 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 = "Main Title String"
Chart.HasSubTitle = True
Chart.Subtitle.String = "Subtitle String"
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 chart has a background area. The Chart object provides the property Area to format the background:

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

The background of a chart covers its complete area, including the area under the title, subtitle and legend. The associated com.sun.star.chart.ChartArea service supports line and fill properties.

Diagram

The Chart object provides the property Diagram which forms the coordinate system with axes and grids, where the data finally is displayed:

Diagram (Object): object forming the coordinate system where the data is plotted

(supports com.sun.star.chart.Diagram service and com.sun.star.chart.StackableDiagram, com.sun.star.chart.ChartAxisXSupplier, com.sun.star.chart.ChartAxisYSupplier, com.sun.star.chart.ChartAxisZSupplier, com.sun.star.chart.ChartTwoAxisXSupplier and com.sun.star.chart.ChartTwoAxisYSupplier service). Dependent on the chart type different services are supported (see next section http://wiki.services.openoffice.org/wiki/Documentation/BASIC_Guide/Chart_Types).

Chart Walls and Floor

The chart wall is the background of the coordinate system where the data is plotted. Two chart walls usually exist for 3D charts: one behind the plotted data and one as the left-hand or right-hand demarcation. This depends on the rotation of the chart. 3D charts usually also have a floor.

The Diagram object provides the properties Wall and Floor:

Wall (Object): background wall of the coordinate system (supports com.sun.star.chart.ChartArea service).
Floor (Object): floor panel of coordinate system (only for 3D charts, supports com.sun.star.chart.ChartArea service).

The specified objects support the com.sun.star.chart.ChartArea service, which provides the usual fill and line properties (com.sun.star.drawing.FillProperties and com.sun.star.drawing.LineProperties services, refer to [html/p27.html Chapter 8, Drawings and Presentations]).

The following example shows how graphics (named Sky) already contained in Apache OpenOffice can be used as a background for a chart. The wall is set to be blue.

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
 
Chart.Diagram.Wall.FillStyle = com.sun.star.drawing.FillStyle.SOLID
Chart.Diagram.Wall.FillColor = RGB(00,132,209)

Axes

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

The Diagram object provides the following properties to access the axes:

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 the labels for the interval marks for the X-axis.

HasYAxis (Boolean): activates the Y-axis.
YAxis (Object): object with detailed information about the Y-axis (supports com.sun.star.chart.ChartAxis service).
HasYAxisDescription (Boolean): activates the labels for the interval marks for the Y-axis.

HasZAxis (Boolean): activates the Z-axis.
ZAxis (Object): object with detailed information about the Z-axis (supports com.sun.star.chart.ChartAxis service).
HasZAxisDescription (Boolean): activates the labels for the interval marks for the Z-axis.

HasSecondaryXAxis (Boolean): activates the secondary X-axis.
SecondaryXAxis (Object): object with detailed information about the secondary X-axis (supports com.sun.star.chart.ChartAxis service).
HasSecondaryXAxisDescription (Boolean): activates the labels for the interval marks for the secondary X-axis.

HasSecondaryYAxis (Boolean): activates the secondary Y-axis.
SecondaryYAxis (Object): object with detailed information about the secondary Y-axis (supports com.sun.star.chart.ChartAxis service).
HasSecondaryYAxisDescription (Boolean): activates the labels for the interval marks for the secondary Y-axis.

Properties of an Axes

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

Scaling 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 the major interval marks.
StepHelp (Double): distance between the minor interval marks (deprecated since OpenOffice.org 3.0; Use property StepHelpCount instead).
StepHelpCount (Long): Contains the number of minor intervals within a major interval. E.g. a StepHelpCount of 5 divides the major interval into 5 pieces and thus producces 4 minor tick marks. (availabel since OpenOffice.org 3.0).
AutoMax (Boolean): the maximum value for the axis is calculated automatically when set to true.
AutoMin (Boolean): the minimum value for the axis is calculated automatically when set to true.
AutoOrigin (Boolean): the origin is determines automatically when set to true.
AutoStepMain (Boolean): StepMain is determines automatically when set to true.
AutoStepHelp (Boolean): StepHelpCount is determines automatically when set to true.
Logarithmic (Boolean): scales the axes in logarithmic manner (rather than linear).
ReverseDirection (Boolean): determines if the axis orientation is mathematical or reversed. (available since OpenOffice.org 2.4)

Label properties:

DisplayLabels (Boolean): activates the text label at the interval marks.
TextRotation (Long): angle of rotation of text label in 100ths of a degree.
ArrangeOrder (enum): the label may be staggered, thus they are positioned alternately over two lines (values according to com.sun.star.chart.ChartAxisArrangeOrderType)
TextBreak (Boolean): permits line breaks within the axes labels.
TextCanOverlap (Boolean): permits an overlap of the axes labels.
NumberFormat (Long): number format to be used with the axes labels (refer to [html/p24.html#fapcj Number, Date and Text Format] section)
LinkNumberFormatToSource (Boolean): determines whether to use the number format given by the container document, or from the property NumberFormat. (since OpenOffice.org 2.3)

Interval mark properties:

Marks (Const): determins the position of the major interval marks (values in accordance with com.sun.star.chart.ChartAxisMarks )
HelpMarks (Const): determins the position of the minor interval marks (values in accordance with com.sun.star.chart.ChartAxisMarks )

Only for bar charts:

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).

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 [html/p27.html 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 chart titles.

Example

The following example creates a line chart. The color for the rear wall of the chart 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 chart 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 Charts

Most charts in Apache OpenOffice can also be displayed with 3D graphics. All chart 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 Charts

Stacked charts are charts 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 Apache OpenOffice, various types of charts can be displayed in a stacked form. All of these charts 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.

Content on this page is licensed under the Public Documentation License (PDL).

@@ Line 143: / Line 143: @@
 {{OOo}} recognizes five different axes that can be used in a chart. In the simplest scenario, these are the X and Y-axes. When working with 3D charts, a Z-axis is also sometimes provided. For charts in which the values of the various rows of data deviate significantly from one another, {{OOo}} provides a second X and Y-axis for second scaling operations.
-=== First X, Y and Z-Axis ===
+The <tt>Diagram</tt> object provides the following properties to access the axes:
-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 chart 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):
 ;<tt>HasXAxis (Boolean)</tt>:activates the X-axis.
 ;<tt>XAxis (Object)</tt>:object with detailed information about the X-axis (supports <tt>com.sun.star.chart.ChartAxis</tt> service).
-;<tt>HasXAxisDescription (Boolean)</tt>:activates description for the X-axis.
+;<tt>HasXAxisDescription (Boolean)</tt>:activates the labels for the interval marks for the X-axis.
-;<tt>HasXAxisGrid (Boolean)</tt>:activates main grid for X-axis.
-;<tt>XMainGrid (Object)</tt>:object with detailed information about main grid for X-axis (supports <tt>com.sun.star.chart.ChartGrid</tt> service).
-;<tt>HasXAxisHelpGrid (Boolean)</tt>:activates auxiliary grid for X-axis.
-;<tt>XHelpGrid (Object)</tt>:object with detailed information about auxiliary grid for X-axis (supports <tt>com.sun.star.chart.ChartGrid</tt> service).
-;<tt>HasXAxisTitle (Boolean)</tt>:activates title of X-axis.
-;<tt>XAxisTitle (Object)</tt>:object with detailed information about title of X-axis (supports <tt>com.sun.star.chart.ChartTitle</tt> service).
-=== Second X and Y-Axis ===
+;<tt>HasYAxis (Boolean)</tt>:activates the Y-axis.
+;<tt>YAxis (Object)</tt>:object with detailed information about the Y-axis (supports <tt>com.sun.star.chart.ChartAxis</tt> service).
+;<tt>HasYAxisDescription (Boolean)</tt>:activates the labels for the interval marks for the Y-axis.
-The following properties are available for the second X and Y-axes (properties taking example of the second X-axis):
+;<tt>HasZAxis (Boolean)</tt>:activates the Z-axis.
+;<tt>ZAxis (Object)</tt>:object with detailed information about the Z-axis (supports <tt>com.sun.star.chart.ChartAxis</tt> service).
+;<tt>HasZAxisDescription (Boolean)</tt>:activates the labels for the interval marks for the Z-axis.
-;<tt>HasSecondaryXAxis (Boolean)</tt>:activates the second X-axis.
+;<tt>HasSecondaryXAxis (Boolean)</tt>:activates the secondary X-axis.
-;<tt>SecondaryXAxis (Object)</tt>:object with detailed information about the second X-axis (supports <tt>com.sun.star.chart.ChartAxis</tt> service).
+;<tt>SecondaryXAxis (Object)</tt>:object with detailed information about the secondary X-axis (supports <tt>com.sun.star.chart.ChartAxis</tt> service).
-;<tt>HasSecondaryXAxisDescription (Boolean)</tt>:activates description of X-axis.
+;<tt>HasSecondaryXAxisDescription (Boolean)</tt>:activates the labels for the interval marks for the secondary X-axis.
-=== Properties of the Axes ===
+;<tt>HasSecondaryYAxis (Boolean)</tt>:activates the secondary Y-axis.
+;<tt>SecondaryYAxis (Object)</tt>:object with detailed information about the secondary Y-axis (supports <tt>com.sun.star.chart.ChartAxis</tt> service).
+;<tt>HasSecondaryYAxisDescription (Boolean)</tt>:activates the labels for the interval marks for the secondary Y-axis.
+=== Properties of an Axes ===
 The axis objects of a {{OOo}} chart support the <tt>com.sun.star.chart.ChartAxis</tt> service. In addition to the properties for characters <tt>(com.sun.star.style.CharacterProperties</tt> service, refer to [html/p19.html Chapter 6, Text Documents]) and lines <tt>(com.sun.star.drawing.LineStyle</tt> service, refer to [html/p27.html Chapter 8, Drawings and Presentations]), it provides the following properties:
+Scaling properties:
 ;<tt>Max (Double)</tt>:maximum value for axis.
 ;<tt>Min (Double)</tt>:minimum value for axis.
 ;<tt>Origin (Double)</tt>:point of intersect for crossing axes.
-;<tt>StepMain (Double)</tt>:distance between two primary lines of the axis.
+;<tt>StepMain (Double)</tt>:distance between the major interval marks.
-;<tt>StepHelp (Double)</tt>:distance between two secondary lines of the axis.
+;<tt>StepHelp (Double)</tt>:distance between the minor interval marks (deprecated since OpenOffice.org 3.0; Use property StepHelpCount instead).
-;<tt>AutoMax (Boolean)</tt>:automatically determines maximum value for axis.
+;<tt>StepHelpCount (Long)</tt>:Contains the number of minor intervals within a major interval. E.g. a StepHelpCount of 5 divides the major interval into 5 pieces and thus producces 4 minor tick marks. (availabel since OpenOffice.org 3.0).
-;<tt>AutoMin (Boolean)</tt>:automatically determines minimum value for axis.
+;<tt>AutoMax (Boolean)</tt>:the maximum value for the axis is calculated automatically when set to true.
-;<tt>AutoOrigin (Boolean)</tt>:automatically determines point of intersect for crossing axes.
+;<tt>AutoMin (Boolean)</tt>:the minimum value for the axis is calculated automatically when set to true.
-;<tt>AutoStepMain (Boolean)</tt>:automatically determines distance between primary lines of an axis.
+;<tt>AutoOrigin (Boolean)</tt>:the origin is determines automatically when set to true.
-;<tt>AutoStepHelp (Boolean)</tt>:automatically determines distance between secondary lines of an axis.
+;<tt>AutoStepMain (Boolean)</tt>:StepMain is determines automatically when set to true.
-;<tt>Logarithmic (Boolean)</tt>:scales the axes in logarithmic manner (rather than linear manner).
+;<tt>AutoStepHelp (Boolean)</tt>:StepHelpCount is determines automatically when set to true.
-;<tt>DisplayLabels (Boolean)</tt>:activates the text label for axes.
+;<tt>Logarithmic (Boolean)</tt>:scales the axes in logarithmic manner (rather than linear).
-;<tt>TextRotation (Long)</tt>:angle of rotation of text label of axes in 100ths of a degree.
+;<tt>ReverseDirection (Boolean)</tt>:determines if the axis orientation is mathematical or reversed. (available since OpenOffice.org 2.4)
-;<tt>Marks (Const)</tt>:constant that specifies whether the primary lines of the axis should be inside or outside the chart area (default values in accordance with <tt>com.sun.star.chart.ChartAxisMarks</tt> )
-;<tt>HelpMarks (Const)</tt>:constant that specifies whether the secondary lines of the axis should be inside and/or outside the chart area (default values in accordance with <tt>com.sun.star.chart.ChartAxisMarks</tt> )
+Label properties:
+;<tt>DisplayLabels (Boolean)</tt>:activates the text label at the interval marks.
+;<tt>TextRotation (Long)</tt>:angle of rotation of text label in 100ths of a degree.
+;<tt>ArrangeOrder (enum)</tt>:the label may be staggered, thus they are positioned alternately over two lines (values according to <tt>com.sun.star.chart.ChartAxisArrangeOrderType</tt>)
+;<tt>TextBreak (Boolean)</tt>:permits line breaks within the axes labels.
+;<tt>TextCanOverlap (Boolean)</tt>:permits an overlap of the axes labels.
+;<tt>NumberFormat (Long)</tt>:number format to be used with the axes labels (refer to [html/p24.html#fapcj Number, Date and Text Format] section)
+;<tt>LinkNumberFormatToSource (Boolean)</tt>:determines whether to use the number format given by the container document, or from the property <tt>NumberFormat</tt>. (since OpenOffice.org 2.3)
+Interval mark properties:
+;<tt>Marks (Const)</tt>:determins the position of the major interval marks (values in accordance with <tt>com.sun.star.chart.ChartAxisMarks</tt> )
+;<tt>HelpMarks (Const)</tt>:determins the position of the minor interval marks (values in accordance with <tt>com.sun.star.chart.ChartAxisMarks</tt> )
+Only for bar charts:
 ;<tt>Overlap (Long)</tt>: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).
 ;<tt>GapWidth (long)</tt>: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).
-;<tt>ArrangeOrder (enum)</tt>: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 <tt>com.sun.star.chart.ChartAxisArrangeOrderType</tt>)
-;<tt>TextBreak (Boolean)</tt>:permits line breaks.
-;<tt>TextCanOverlap (Boolean)</tt>:permits text overlaps.
-;<tt>NumberFormat (Long)</tt>:number format (refer to [html/p24.html#fapcj Number, Date and Text Format] section)
 === Properties of the axis grid ===