.. sectionauthor:: jo, benjamin
.. _ref-charts-started:
###############################################################################
Getting Started
###############################################################################
MaongoMP bietet für das automatische Platzieren von Labels und für die Anbindung von dynamischen Daten und daraus resultierenden automatischen Layouts ein ganzes Subsystem an Optionen an, die es erlauben, so gut wie jeden Gestaltungswunsch umzusetzen.
Um allerdings einfach loslegen zu können, lohnt es sich, zunächst einmal ein Minimalchart ohne diese Features zu bauen.
Minimalistisch...
-------------------------------------------------------------------------------
Ein einfaches BalkenChart könnte so erzeugt werden::
Beispiel 1:
.. image:: ../images/6_1_1.png
Das Barchart nutzt die Liste von vier zugewiesenen Werten, um Balken in der (angegebenen oder ererbten) ``ForegroundColor`` zu zeichnen. Es ordnet die Balken automatisch innerhalb des durch ``Shape`` und ``Padding`` angegebenen Bereichs an. Dasselbe funktioniert auch horizontal::
Beispiel 2:
.. image:: ../images/6_1_2.png
Eine minimalistische Umsetzung eines Linecharts wäre::
Beispiel 3:
.. image:: ../images/6_1_3.png
Das Beispiel skaliert die Werte im verfügbaren Raum und zeichnet eine Linie in der ``ForegroundColor`` mit den in ``Values`` angegebenen Werten. Da eine Linie aus einer Liste von Werten besteht, und in einem LineChart mehrer Linien gezeichnet werden können, werden die ``Values`` als Liste von Listen (für jede Linie eine Liste) notiert. Hier ein LineChart mit drei Linien::
Beispiel 4:
.. image:: ../images/6_1_4.png
Die Farben der Linien werden mit einer Liste von Farben in der Property ``Colors`` gesetzt. Wenn mehr Linien als Farbeinträge vorhanden sind, wird wieder von vorne aus der Liste ausgelesen.
Beispiel 5 zeichnet eine minimalistische Tortengrafik::
Beispiel 5:
.. image:: ../images/6_1_5.png
Auch hier werden die Standardeinstellungen des Charttyps genutzt, um ein Kreischart zentriert in die Mitte des verfügbaren Raums zu zeichnen.
Mit geringen Modifikationen können wir auch ein Halbkreis- und eine ellipsoides Chart zeichnen::
Beispiel 6:
.. image:: ../images/6_1_6.png
Auch in diesem Beispiel haben wir die Property ``Colors`` genutzt, um die einzelnen Segmente einzufärben. Im ellipsoiden Chart haben wir den Farben zusätzlich Transparenz gegeben.
Die bisher beschriebenen minimalistischen Ansätze reichen häufig nicht aus, um komplexere Charts zu erstellen: wir wollen Balken, Linien und Kreissegmente beschriften, wollen Data (siehe --> Data) nutzen, um Werte des Charts und der Labels zu setzen, und wollen häufig auch die Labels in spezifischer Art und Weise um die Charts gruppieren oder an Werte des Charts koppeln.
Bevor wir solch komplexe Charts erstellen, hier noch eine ziemlich minimalistische Version eines PieCharts mit einfachen Labels::
Beispiel 7:
.. image:: ../images/6_1_7.png
Hier haben wir unter dem PieChartWidget zwei LabelBarWidgets angeordnet, die für jedes ihrer Values ein neues Element aus einem Template generieren. Die Templates, die in einem LabelBar benutzt werden sollen, müssen als Liste aus Template-Referenzen in der Property ``LabelTemplates`` gesetzt werden. Die zweite LabelBar zeigt, daß das benutzte Template auch an anderer Stelle im Mad stehen kann. Mehr zu Templates und ihrer Benutzung im folgenden Absatz:
Templates nutzen
-------------------------------------------------------------------------------
Alle Charts können für die wiederholten Elemente (Balken, Linien, Kreissegmente, Labels) Templates nutzen. Templates sind ja bekanntlich (--> :ref:`ref-templates-in-mad` ) beliebige Widgets, die bei der Ausführung der Presentation initialisiert (und im Fall eines Charts mehrfach automatisch eingesetzt) werden.
Wenn wir das Beispiel 5 von oben so modifizieren wollen, dass jedes Kreissegment eine anderes Template mit unterschiedlichen Farben enthält, so können wir so vorgehen::
Beispiel 8:
.. image:: ../images/6_1_8.png
Die Property ``PieTemplates`` erhält hier eine Liste von Templatenamen zugewiesen, die für das PieChartWidget per Lookup erreichbar sein müssen. Es nutzt diese Templates der Reihe nach, um die Werte damit als Kreissegmente zu zeichnen.
Ebenso könnten wir aber auch entscheiden, dass ein Template mehrfach genutzt werden soll. Auch ein Button kann hier als Template verwendet werden::
Beispiel 9:
this.BackgroundColor = "red";
.. image:: ../images/6_1_9.png
Hier wird das Template mybutton für die Darstellung aller Segmente benutzt. Ein Klick auf ein Kreissegment färbt es rot.
Chart und Templates an Data binden
-------------------------------------------------------------------------------
Bereits Beispiel 8 und 9 wecken weitere Wünsche: Es wäre sehr praktisch, unser Chart und die zum Zeichnen verwendeten Templates an die Werte eines auf das Widget gerouteten Data binden zu können.
Angenommen, wir haben ein Data, das auf einem Button definiert ist und so aussieht::
Beispiel 10:
| Hans |
#cc0000 |
1.0 |
-1.0 |
Gruppe 1 |
../images/hans.png |
| Peter |
#00cc00 |
3.0 |
-1.5 |
Gruppe 1 |
../images/peter.png |
| Dieter |
#0000cc |
5.0 |
0.5 |
Gruppe 2 |
../images/dieter.png |
| Georg |
#cc00cc |
9.5 |
3.0 |
Gruppe 2 |
../images/georg.png |
Ein Klick auf den Button leitet das Data zum Widget ``TheChart`` weiter::
Beispiel 10 cont'd:
Wir sehen, dass es Properties gibt, denen Wertelisten zugewiesen werden, da sie für das ganze Chart gelten: ``Values`` und ``Groups`` (letztere erlaubt uns, mit ``GroupMetrics`` die Balken des BarCharts zu gruppieren).
Daneben gibt es Properties im Template, die wir an einen bestimmten Wert einer Liste binden wollen. Dazu dient das Objekt "Controller.current": beim Erzeugen des Charts wird für jeden Wert eine Kopie des Templates erzeugt. Diese Kopie wird mit den Binding-Angaben (hier für ``Texture`` und ``BorderColor`` an den gerade aktuellen Index (= ``current``) des Controller-Objekts gebunden und erhält den unter ``key`` verfügbaren Wert, hier also eine Farbe und ein Bild.
Die LabelBars können sich an den Controller des PieCharts binden und von dort Ihre ``Values`` füllen.
Nun wollen wir auch endlich die LabelBar für die Zahlenwerte mit einem Textwidget formatieren. In diesem Fall binden wir nicht nur die Werteliste, sondern im Template auch die einzelnen Werte mit ``current``::
Beispiel 10 cont'd:
.. image:: ../images/6_1_10.png
Raster und Layout zur Platzierung der Labels nutzen
-------------------------------------------------------------------------------
In manchen Situationen ist es nötig, die Positionierung der Labels nicht unabhängig vom (Balken-, Linien-)Chart vorzunehmen, sondern an die Positionen im gezeichneten Chart zu koppeln. Die LabelBars, die wir in den bisherigen Beispielen mit den Charts verwendet haben, bieten diese Möglichkeit nicht: sie sind unabhängige Widgets, die ihre eigene Layout-Funktionalität nutzen.
In einem gruppierten Säulenchart werden die Säulen auseinander gerückt: Die Labels sollten dem folgen. Dies erreichen wir, indem wir im BarChart ein einfaches Raster für die Labels definieren und mit LayoutConstraints die Labelpositionierung festlegen.
::
Beispiel 11:
Databutton wie oben
Wir haben hier ein BarChart soweit vorbereitet wie in Beispiel 10 das PieChart.
Neu hinzugekommen ist die Definition eines horizontalen und eines vertikalen Rasters. Was noch fehlt, ist die in ElementLabels genannten Templates zu definieren und in dieser Definition die Verortung im Raster zu benennen.
Die Balken werden per Konvention in der Rasterposition ``chart-chart`` (also ``HorizontalRasterPosition=chart`` und ``VerticelRasterPosition=chart``) gezeichnet.
Mit der Property ``GroupMetrics`` haben wir außerdem festgelegt, dass zwischen den beiden Gruppen von Balken ein Abstand von 20px gezeichnet werden soll. ``BarMetrics`` sorgt für den Abstand zwischen den Balken.
Definition der Templates für die Labels und die Balken::
Beispiel 11 cont'd:
.. image:: ../images/6_1_11.png
Wir sehen, dass die Labels wie vorgegeben an unterschiedlichen vertikalen Positionen gezeichnet werden. Die Gruppierung wirkt sich in erster Linie auf die Säulen aus; da die Labels über das Raster aber an die Säulenpositionen gebunden sind, sehen wir bei ihnen denselben Gruppenabstand.
Nähere Informationen zum LayoutRaster und den möglichen LayoutConstraints siehe im Kapitel :ref:`ref-charts-raster`.
Test: See :download:`this example script <../../reference/charts/getting_started/11.mad>`.