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

From Apache OpenOffice Wiki
Jump to: navigation, search
(Stacked Charts)
Line 230: Line 230:
 
;<tt>Stacked (Boolean)</tt>:activates the stacked viewing mode.
 
;<tt>Stacked (Boolean)</tt>:activates the stacked viewing mode.
 
;<tt>Percent (Boolean)</tt>:rather than absolute values, displays their percentage distribution.
 
;<tt>Percent (Boolean)</tt>:rather than absolute values, displays their percentage distribution.
 
  
 
{{PDL1}}
 
{{PDL1}}

Revision as of 11:49, 19 March 2008

Template:Documentation/NeedsRework


The structure of a chart — 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 charts, but not in 2D charts. In pie charts, there are no interfaces for working with axes.

The Individual Elements of a Chart

Title, Sub-title and Key

A title, sub-title and key form part of the basic elements of every chart. Charts 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 chart title (supports the com.sun.star.chart.ChartTitle service).
HasSubTitle(Boolean)
activates the sub-title.
Subtitle (Object)
object with detailed information about the chart 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 chart (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 chart 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 chart 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 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 = "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 chart has a background area. Every area has an object, which can be accessed using the following properties of the chart object:

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, sub-title and chart key. The associated com.sun.star.chart.ChartArea service supports line and fill properties and provides no more extensive properties.

Chart Walls and Floors

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

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

Floor (Object)
floor panel of the chart (only for 3D charts, supports com.sun.star.chart.ChartArea service).
Wall (Object)
chart walls (only for 3D charts, 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 [html/p27.html Chapter 8, Drawings and Presentations]).

The chart 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 Apache OpenOffice can be used as a background to a chart.

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

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.

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

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 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:

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 chart 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 chart 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 [html/p24.html#fapcj 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 [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).
Personal tools