Kapitel 9 Diagramme (Charts)

StarOffice kann Daten als Diagramme darstellen und so diese Daten in Form von Balken, Kuchenstücken, Linien oder anderen Elementen grafisch zueinander in Bezug setzen. Die Ausgabe kann wahlweise als 2D- oder 3D-Grafik erfolgen, wobei das Aussehen der Diagrammelemente, ähnlich wie beim Zeichnen von Elementen, individuell angepasst werden kann.

Liegen die darzustellenden Daten als Tabellendokument vor, so lassen sich diese dynamisch mit dem Diagramm verknüpfen. Änderungen der Basisdaten werden in diesem Fall sofort im zugeordneten Diagramm sichtbar. Dieses Kapitel bietet einen Überblick über die Programmierschnittstelle des Diagramm-Moduls von StarOffice, wobei der Schwerpunkt auf dem Einsatz von Diagrammen innerhalb von Tabellendokumenten liegt.

Verwenden von Diagrammen in Tabellendokumenten

Diagramme werden in StarOffice nicht als unabhängige Dokumente behandelt, sondern als Objekte, die in ein existierendes Dokument eingebettet sind.

Während Diagramme in Text- und Zeichnungsdokumenten isoliert vom Inhalt des Dokumentes stehen, steht bei ihrem Einsatz in Tabellendokumenten ein Mechanismus zur Verfügung, der eine Verknüpfung der Dokumentdaten mit den eingebetteten Diagrammen gestattet. Das folgende Beispiel erläutert das Zusammenspiel zwischen Tabellendokument und Diagramm:

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)

Obwohl der Beispielcode recht komplex erscheinen mag, beschränken sich die zentralen Vorgänge auf drei Zeilen: In der ersten zentralen Zeile wird die Dokumentvariable Doc erzeugt, die auf das aktuelle Tabellendokument verweist (Zeile Doc = StarDesktop.CurrentComponent). Im Anschluss daran erstellt der Beispielcode eine Liste mit allen Diagrammen des ersten Tabellendokuments (Zeile Charts = Doc.Sheets(0).Charts). Dieser Liste wird schließlich in der letzten Zeile des Beispiels mit der Methode addNewByName ein neues Diagramm hinzugefügt, das dann dem Anwender angezeigt wird.

In der letzten Zeile werden die Hilfsstrukturen Rect und RangeAddress initialisiert, die ebenfalls Parameter der Methode addNewByName sind. Durch Rect wird die Position des Diagramms innerhalb des Tabellendokuments bestimmt. Mit RangeAddress wird der Bereich festgelegt, dessen Daten mit dem Diagramm verknüpft werden sollen.

Das obige Beispiel erzeugt ein Balkendiagramm. Wird ein anderer Diagrammtyp benötigt, so muss das Balkendiagramm explizit ausgetauscht werden:

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

In der ersten Zeile wird das entsprechende Chart-Objekt (Diagramm) definiert. In der zweiten Zeile wird das aktuelle Diagramm durch ein neues ausgetauscht – im Beispiel ein Liniendiagramm.

---

Hinweis –

In Excel wird unterschieden zwischen Diagrammen, die als eigenständige Seite in ein Excel-Dokument eingefügt wurden, und Charts, die in eine Tabellenseite eingebettet sind. Dementsprechend sind dort zwei verschiedene Zugriffsmöglichkeiten auf Diagramme definiert. Diese Unterscheidung entfällt in StarOffice Basic, da Diagramme in StarOffice Calc immer als eingebettete Objekte einer Tabellenseite erzeugt werden. Der Zugriff auf diese Diagramme erfolgt hierbei immer über die Liste Charts des zugehörigen Sheet-Objekts.

---

Der Aufbau von Diagrammen

Der Aufbau eines Diagramms – und damit die Liste der von ihm unterstützten Dienste und Schnittstellen – hängt von seinem Typ ab. So stehen die Methoden und Eigenschaften der Z-Achse beispielsweise nur in 3D-Diagrammen zur Verfügung, nicht jedoch in 2D-Diagrammen. In Tortendiagrammen gibt es keine Schnittstellen zum Arbeiten mit Achsen.

Die Einzelelemente eines Diagramms

Titel, Untertitel und Legende

Zu den Basiselementen eines jeden Diagramms gehören ein Titel, ein Untertitel und eine Legende. Diagramme stellen für jedes dieser Elemente eigene Objekte zur Verfügung. Das Chart-Objekt bietet zur Verwaltung dieser Elemente folgende Eigenschaften:

• HasMainTitle (Boolean): aktiviert den Titel.

• Title (Object): Objekt mit Detailangaben zum Diagrammtitel (unterstützt den Dienst com.sun.star.chart.ChartTitle).

• HasSubTitle (Boolean): aktiviert den Untertitel.

• Subtitle (Object): Objekt mit Detailangaben zum Diagrammuntertitel (unterstützt den Dienst com.sun.star.chart.ChartTitle).

• HasLegend (Boolean): aktiviert die Legende.

• Legend (Object): Objekt mit Detailangaben zur Legende des Diagramms (unterstützt den Dienst com.sun.star.chart.ChartLegendPosition).

Die genannten Elemente entsprechen in vieler Hinsicht einem Zeichnungselement. Dies liegt daran, dass die beiden Dienste com.sun.star.chart.ChartTitle und com.sun.star.chart.ChartLegendPosition den Dienst com.sun.star.drawing.Shape unterstützen, der die programmtechnische Grundlage für Zeichnungselemente legt.

So besteht die Möglichkeit, die Position und Größe der Elemente über die Eigenschaften Size und Position zu bestimmen.

Für die Formatierung der Elemente stehen des Weiteren Füll- und Linien-Eigenschaften (Dienste com.sun.star.drawing.FillProperties und com.sun.star.drawing.LineStyle) sowie Zeichen-Eigenschaften (Dienst com.sun.star.style.CharacterProperties) zur Verfügung.

com.sun.star.chart.ChartTitle besitzt neben den genannten Format-Eigenschaften zwei weitere Eigenschaften:

• TextRotation (Long): Drehwinkel des Texts in 100stel Grad.

• String (String): Text, der als Titel oder Untertitel angezeigt werden soll.

Die Legende des Diagramms (Dienst com.sun.star.chart.ChartLegend) besitzt folgende zusätzliche Eigenschaft:

• Alignment (Enum): Position, an der die Legende angezeigt werden soll (Standardwert gemäß com.sun.star.chart.ChartLegendPosition).

Das folgende Beispiel erzeugt ein Diagramm und weist ihm den Titel "Test", den Untertitel "Test 2" und eine Legende zu. Die Legende erhält eine graue Hintergrundfarbe, wird am unteren Rand des Diagramms platziert und verfügt über eine Schriftgröße von 7 Punkt.

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

Hintergrund

Jedes Diagramm besitzt eine Hintergrundfläche. Für jede Fläche ist ein Objekt vorhanden, auf das über folgende Eigenschaften des Diagramm-Objekts zugegriffen werden kann:

• Area (Object): Hintergrundfläche des Diagramms (unterstützt den Dienst com.sun.star.chart.ChartArea).

Der Hintergrund eines Diagramms umfasst dessen komplette Fläche, einschließlich der Flächen hinter Titel, Untertitel und Diagramm-Legende. Der verknüpfte Dienst com.sun.star.chart.ChartArea unterstützt Linien- und Füll-Eigenschaften und stellt keine weitergehenden Eigenschaften zur Verfügung.

Diagrammwände und -böden

Während der Diagrammhintergrund die vollständige Fläche des Diagramms umfasst, ist die Diagrammrückwand auf die Fläche unmittelbar hinter dem Datenbereich beschränkt.

Bei 3D-Diagrammen existieren für gewöhnlich zwei Diagrammwände: eine hinter dem Datenbereich und eine als linke Begrenzung der Y-Achse. Zusätzlich enthalten 3D-Diagramme in der Regel einen Boden.

• Floor (Object): Bodenpanel des Diagramms (nur bei 3D-Diagrammen, unterstützt den Dienst com.sun.star.chart.ChartArea).

• Wall (Object): Diagrammwände (nur bei 3D-Diagrammen, unterstützt den Dienst com.sun.star.chart.ChartArea).

Die angegebenen Objekte unterstützen den Dienst com.sun.star.chart.ChartArea, der wiederum die gängigen Füll- und Linien-Eigenschaften bereitstellt (Dienste com.sun.star.drawing.FillProperties und com.sun.star.drawing.LineStyle, siehe Kapitel 8, Zeichnungen und Präsentationen).

Der Zugriff auf Diagrammwände und -böden erfolgt über das Chart-Objekt, das wiederum Bestandteil des Chart-Objekts ist:

Chart.Area.FillBitmapName = "Sky"

Das folgende Beispiel zeigt, wie sich eine bereits in StarOffice eingebundene Grafik mit dem Namen „Sky” als Hintergrund eines Diagramms einsetzen lässt.

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

Achsen

StarOffice erkennt fünf verschiedene Achsen, die in einem Diagramm zum Einsatz kommen können. Im einfachsten Falle sind dies die X- und Y-Achse. Bei 3D-Diagrammen steht teilweise zusätzlich eine Z-Achse zur Verfügung. In Diagrammen, bei denen die Werte der verschiedenen Datenzeilen stark voneinander abweichen, bietet StarOffice eine zweite X- und Y-Achse für eine zweite, abweichende Skalierung an.

Erste X-, Y- und Z-Achse

Für jede der ersten X-, Y- und Z-Achse können neben der eigentlichen Achse ein Titel, eine Beschreibung, ein Gitter und ein Hilfsgitter vorhanden sein. Alle dieser Elemente können wahlweise ein- und ausgeblendet werden. Das Diagramm-Objekt bietet zur Verwaltung dieser Elemente folgende Eigenschaften an (im Beispiel die X-Achse; die Eigenschaften für Y- und Z-Achse sind analog aufgebaut):

• HasXAxis (Boolean): aktiviert die X-Achse.

• XAxis (Object): Objekt mit Detailinformationen zur X-Achse (unterstützt den Dienst com.sun.star.chart.ChartAxis).

• HasXAxisDescription (Boolean): aktiviert die Beschreibung der X-Achse.

• HasXAxisGrid (Boolean): aktiviert das Hauptgitter für die X-Achse.

• XMainGrid (Object): Objekt mit Detailinformationen zum Hauptgitter der X-Achse (unterstütz den Dienst com.sun.star.chart.ChartGrid).

• HasXAxisHelpGrid (Boolean): aktiviert das Hilfsgitter für die X-Achse.

• XHelpGrid (Object): Objekt mit Detailinformationen zum Hilfsgitter der X-Achse (unterstützt den Dienst com.sun.star.chart.ChartGrid).

• HasXAxisTitle (Boolean): aktiviert den Titel der X-Achse.

• XAxisTitle (Object): Objekt mit Detailinformationen zum Titel der X-Achse (unterstützt den Dienst com.sun.star.chart.ChartTitle).

Zweite X- und Y-Achse

Für die zweite X- und Y-Achse stehen folgende Eigenschaften zur Verfügung (Eigenschaften am Beispiel der zweiten X-Achse):

• HasSecondaryXAxis (Boolean): aktiviert die zweite X-Achse.

• SecondaryXAxis (Object): Objekt mit Detailinformationen zur zweiten X-Achse (unterstützt den Dienst com.sun.star.chart.ChartAxis).

• HasSecondaryXAxisDescription (Boolean): aktiviert die Beschreibung der X-Achse.

Eigenschaften der Achsen

Die Achsen-Objekte eines StarOffice-Diagramms unterstützen den Dienst com.sun.star.chart.ChartAxis. Er stellt neben den Eigenschaften für Zeichen (Dienst com.sun.star.style.CharacterProperties, siehe Kapitel 6, Textdokumente) und Linien (Dienst com.sun.star.drawing.LineStyle, siehe Kapitel 8, Zeichnungen und Präsentationen) folgende Eigenschaften zur Verfügung:

• Max (Double): Maximalwert für die Achse.

• Min (Double): Minimalwert für die Achse.

• Origin (Double): Schnittpunkt bei sich schneidenden Achsen (Ursprung).

• StepMain (Double): Abstand zwischen zwei Hauptstrichen der Achse.

• StepHelp (Double): Abstand zwischen zwei Hilfsstrichen der Achse.

• AutoMax (Boolean): ermittelt automatisch den Maximalwert für die Achse.

• AutoMin (Boolean): ermittelt automatisch den Minimalwert für die Achse.

• AutoOrigin (Boolean): ermittelt automatisch den Schnittpunkt sich schneidender Achsen (Ursprung).

• AutoStepMain (Boolean): ermittelt automatisch den Abstand zwischen Hauptstrichen einer Achse.

• AutoStepHelp (Boolean): ermittelt automatisch den Abstand zwischen Hilfsstrichen einer Achse.

• Logarithmic (Boolean): skaliert die Achsen in logarithmischem Maßstab (statt linear).

• DisplayLabels (Boolean): aktiviert die Textbeschriftung für Achsen.

• TextRotation (Long): Drehwinkel der Textbeschriftung von Achsen in 100stel Grad.

• Marks (Const): Konstante, die angibt, ob die Hauptstriche der Achse innerhalb oder außerhalb der Diagrammfläche liegen sollen (Standardwerte gemäß com.sun.star.chart.ChartAxisMarks).

• HelpMarks (Const): Konstante, die angibt, ob die Hilfsstriche der Achse innerhalb und/oder außerhalb der Diagrammfläche liegen sollen (Standardwerte gemäß com.sun.star.chart.ChartAxisMarks).

• Overlap (Long): Prozentwert, der angibt, wie weit sich die zu unterschiedlichen Datensätzen gehörenden Balken überlappen dürfen (bei 100% werden die Balken komplett überlagert dargestellt, bei -100% besteht zwischen ihnen ein Abstand von einer Balkenbreite).

• GapWidth (Long): Prozentwert, der angibt, welcher Abstand zwischen den verschiedenen Balkengruppen eines Diagramms vorhanden sein darf (bei 100% besteht ein Abstand von einer Balkenbreite).

• ArrangeOrder (Enum): Detailangaben zur Position der Beschriftung; neben der Positionierung auf einer Linie besteht die Möglichkeit, die Beschriftung alternierend auf zwei Linien zu verteilen (Standardwert gemäß com.sun.star.chart.ChartAxisArrangeOrderType)

• TextBreak (Boolean): ermöglicht Zeilenumbrüche.

• TextCanOverlap (Boolean): ermöglicht Textüberlappungen.

• NumberFormat (Long): Zahlenformat (siehe Abschnitt Zahlen-, Datums- und Textformat)

Eigenschaften des Achsengitters

Das Objekt für das Achsengitter basiert auf dem Dienst com.sun.star.chart.ChartGrid, der wiederum die Linien-Eigenschaften des Dienstes com.sun.star.drawing.LineStyle unterstützt (siehe Kapitel 8, Zeichnungen und Präsentationen).

Eigenschaften der Achsentitel

Die Objekte zur Formatierung des Achsentitels basieren auf dem Dienst com.sun.star.chart.ChartTitle, der auch beim Diagrammtitel zum Einsatz kommt.

Beispiel

Das folgende Beispiel erstellt ein Linien-Diagramm. Die Farbe für die Rückwand des Diagramms wird auf Weiß gesetzt. Sowohl die X- als auch die Y-Achse erhalten ein graues Hilfsgitter zur visuellen Orientierung. Der Minimalwert der Y-Achse wird fest auf 0 und der Maximalwert fest auf 100 gesetzt, so dass die Auflösung des Diagramms auch bei Änderungen der Werte erhalten bleibt.

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

Die meisten Diagramme in StarOffice können auch dreidimensional (3D) dargestellt werden. Alle Diagrammtypen, die diese Möglichkeit bieten, unterstützen den Dienst com.sun.star.chart.Dim3DDiagram. Der Dienst stellt lediglich eine Eigenschaft zur Verfügung:

• Dim3D (Boolean): aktiviert die 3D-Darstellung.

Gestapelte Diagramme

Unter einer gestapelten Diagrammdarstellung versteht man das Übereinanderordnen mehrerer Einzelwerte zu einem Gesamtwert. Eine solche Darstellung vermittelt damit neben den Einzelwerten einen Überblick zur Gesamtentwicklung.

In StarOffice lassen sich verschiedene Diagrammarten in gestapelter Form darstellen. Alle diese Diagramme unterstützen den Dienst com.sun.star.chart.StackableDiagram, der wiederum folgende Eigenschaften bereitstellt:

• Stacked (Boolean): aktiviert die gestapelte Ansicht.

• Percent (Boolean): stellt statt Absolutwerten ihre prozentuale Verteilung dar.

Diagrammarten

Liniendiagramme

Liniendiagramme (Dienst com.sun.star.chart.LineDiagram) unterstützen eine X-Achse, zwei Y-Achsen und eine Z-Achse. Sie können als 2D- oder 3D-Grafik angezeigt werden (Dienst com.sun.star.chart.Dim3DDiagram). Die Linien sind stapelbar (com.sun.star.chart.StackableDiagram).

Liniendiagramme stellen folgende Eigenschaften zur Verfügung:

• SymbolType (Const): Symbol zum Anzeigen von Datenpunkten (Konstante gemäß com.sun.star.chart.ChartSymbolType).

• SymbolSize (Long): Größe des zum Anzeigen von Datenpunkten verwendeten Symbols in 100stel Millimeter.

• SymbolBitmapURL (String): Dateiname der Grafik zum Anzeigen der Datenpunkte.

• Lines (Boolean): verbindet die Datenpunkte mit Linien.

• SplineType (Long): Spline-Funktion zum Glätten der Linien (0: keine Spline-Funktion, 1: kubische Splines, 2: B-Splines).

• SplineOrder (Long): Polynomial-Gewicht für Splines (nur für B-Splines).

• SplineResolution (Long): Anzahl der Stützpunkte für die Spline-Berechnung.

Flächendiagramme

Flächendiagramme (Dienst com.sun.star.chart.AreaDiagram) unterstützen eine X-Achse, zwei Y-Achsen und eine Z-Achse. Sie können als 2D- oder 3D-Grafik angezeigt werden (Dienst com.sun.star.chart.Dim3DDiagram). Die Flächen sind stapelbar (com.sun.star.chart.StackableDiagram).

Balkendiagramme

Balkendiagramme (Dienst com.sun.star.chart.BarDiagram) unterstützen eine X-Achse, zwei Y-Achsen und eine Z-Achse. Sie können als 2D- oder 3D-Grafik angezeigt werden (Dienst com.sun.star.chart.Dim3DDiagram). Die Balken sind stapelbar (com.sun.star.chart.StackableDiagram).

Sie stellen folgende Eigenschaften zur Verfügung:

• Vertical (Boolean): stellt die Balken senkrecht (vertikal) dar, ansonsten erfolgt die Darstellung waagerecht (horizontal).

• Deep (Boolean): positioniert die Balken bei 3D-Darstellung hintereinander statt nebeneinander.

• StackedBarsConnected (Boolean): verbindet die verknüpften Balken in einem gestapelten Diagramm mit Linien (nur bei horizontalen Diagrammen verfügbar).

• NumberOfLines (Long): Anzahl der Zeilen, die in einem gestapelten Diagramm als Linien statt als Balken dargestellt werden sollen.

Tortendiagramme

Tortendiagramme (Dienst com.sun.star.chart.PieDiagram) enthalten keine Achsen und sind nicht stapelbar. Sie können als 2D- oder 3D-Grafik angezeigt werden (Dienst com.sun.star.chart.Dim3DDiagram).