.. sectionauthor:: malte/jo .. note:: XXXXXXXXXXXXXXX Status 18.10.2010: verbindlich. XXXXXXXXXXXXXXXXXXXX Grid: Kann in einen Abschnitt Gridwidget verschoben werden, wenn andere Charttypen das auch nutzen. .. _ref-linechart: ############################################################################### LineChartWidget *@* ############################################################################### Das LineChart-Widget dient dazu Linien- oder Punkte-Charts inklusive ihrer Labels zu zeichnen, zu animieren und interaktiv zu gestalten. Beispiele --------------------------------------- Einfaches Beispiel eines LineCharts (1 Linie) ohne Labels:: Beispiel 1 Einfaches Beispiel mit mehreren Linien:: Beispiel 2 Daten & Darstellung --------------------------------------- Das LineChartWidget stellt eine oder mehrere Linien dar. Jede Linie besteht aus n zu zeichnenden Werten. Wird "SamplePositions" nicht gesetzt, so geht die Widget-Logik davon aus, dass die Werteangaben in gleichem Abstand linear hintereinander gezeichnet werden sollen. Dieses Verhalten kann durch Samplepositions beeinflusst werden; liegen beispielsweise Werte für die Datumsangaben 1.3.2010, 1.4.2010 und 1.6.2010 vor, die mit den entsprechenden Abständen auf einer Datumsachse angeordnet werden sollen, so lässt sich das mit der Angabe in ``SamplePositions`` erreichen:: Beispiel 3 Damit sind die ersten Elemente der beiden Wertelisten dem Datum 2010-03-01 zugeordnet, die zweiten dem Datum 2010-04-01 und die dritten dem Datum 2010-06-01. Im LineChart wird der Abstand zwischen erstem und zweiten Datenpunkt kleiner Sein als der zwischen zweiten und drittem. SamplePositions können auch für jede Linie getrennt angegeben werden. Hier wird für die zweite Linie auch ein Wert für den 1. Mai angegeben:: Beispiel 4 Die Angaben in ``Minimum`` und ``Maximum`` beziehen sich auf die Skalierung der Werte in Y-Richtung; wie in den anderen Charttypen bieten sie auch im Linechart die Möglichkeit, den darzustellenden Wertebereich anzugeben. Liegen Werte außerhalb dieses Bereichs, so werden sie nicht dargestellt, wenn die entsprechende Einstellung der Property ``AutoScale`` gewählt wird. Um aus der Menge der Samples nur einen Ausschnitt anzuzeigen, gibt es für die X-Achse einen analogen Mechanismus: Mit ``XAxisMinimum``, ``XAxisMaximum`` und der Angabe ``none`` für ``XAxisAutoScale`` lässt sich der Darstellungsbereich in Richtung der X-Achse festlegen. ``XAxisMinimum`` und ``XAxisMaximum`` erwarten dabei SamplePositions als Werte (also Datumsangaben oder den Index des jeweiligen Samples):: Beispiel 5 Dargestellt werden hier nur die erste bis dritte Indexposition der Liste, also die Werte 3, 5 und 7. Der erste Wert hat die Indexposition ``0``. LineWidget nutzen --------------------------------------- Um die Darstellung der Linien im LineChart beeinflussen zu können, kann in der Property ``LineTemplates`` eine Liste von Templates (vom Typ ``Line`` angegeben werden, die der Reihe nach zum Zeichnen der Linien benutzt werden. Vgl. :ref:`ref-line`. Das folgende Beispiel zeichnet 3 Pixel dicke Linien mit Markierungspunkten (Bobbles). Die Bobbles werden im LineTemplate in der Property ``BobbleTemplates`` ebenfalls explizit angegeben:: Beispiel 6 Grid --------------------------------------- Die Darstellung eines Grids im LineChart wird durch die Definition eines Gridwidgets mit ``name="Grid"`` innerhalb des Linechart-Widgets ermöglicht:: Das Gridwidget hat eine Reihe eigener Properties; außerdem nutzt es innerhalb des Linecharts auch dessen AutoScale-Einstellungen und - wenn gewünscht - die ``XAxisAnchors`` und ``YAXisAnchors`` oder die ``SamplePositions``. **Gridbezogene Properties des LineCharts** *ToBeDiscussed* **XAxisGridMode** (Symbol) Werte: ``auto`` (be clever), ``none`` (kein Grid), ``gridwidget`` (Einstellungen des GridWidgets nutzen), ``anchors`` (XAxisAnchors nutzen), ``samples`` (an jeder Sample-Position eine Linie zeichnen) Default: ``gridwidget`` **YAxisGridMode** (Symbol) Werte: ``auto`` (be clever), ``none`` (kein Grid), ``gridwidget`` (Einstellungen des GridWidgets nutzen), ``anchors`` (YAxisAnchors nutzen), ``values`` (für jeden Wert eine Linie zeichnen) Default: ``gridwidget`` **XAxisGridStep** (Number) **later** **YAxisGridStep** (Number) Die Angabe erfolgt in Werteeinheiten. Wenn gesetzt, wird die Property im ``YAxisGridMode = "auto"`` genutzt, um einen bestimmten Abstand der Gridlinien zu erzwingen. **Properties des GridWidgets** Das GridWidget nutzt die folgenden Properties, um ein einfaches Grid zu zeichnen, wenn das ParentChart nicht die Kontrolle übernimmt. **NumberHorizontalLines** (Number) Anzahl der horizontalen Linien, die das Gridwidget platzieren soll. Wenn gesetzt, wird die Angabe für HStep nicht genutzt. Default: ``0`` **HorizontalStep** (Number) Abstand der horizontalen Linien in Pixeln. Wenn gesetzt, wird die Angabe für NumberHLines nicht genutzt. Default: ``0`` **NumberVerticalLines** Anzahl der vertikalen Linien, die das Gridwidget platzieren soll. Wenn gesetzt, wird die Angabe für VStep nicht genutzt. Default: ``0`` **VerticalStep** Abstand der vertikalen Linien in Pixeln. Wenn gesetzt, wird die Angabe für NumberHLines nicht genutzt. Default: ``0`` **ForegroundColor** Das GridWidget nutzt die Widget-Property ``ForegroundColor`` als Grid-Farbe. Beispiel:: Beispiel 6 Im Beispiel wird ein halbtransparentes Grid gezeichnet; die vertikalen Linien befinden sich an allen Samplepositionen; die horizontalen Linien werden automatisch platziert. Da die Werte zwischen 1 und 9 liegen, sind Gridlinien bei 0, 2, 4, 6, 8 zu erwarten. Auto-Modus:: Werte Step Gridlinien 0-10 2 0,2,4,6,... (bis zum höchsten Wert) 0-20 5 0,5,10,... 0-50 10 0,10,20,30,... etc.. Entsprechend die größeren und kleineren Dimensionen: 0-1 0.2 0.2,0.4,0.6,... 0-100 20 20,40,60,... 0-1000 200 200,400,600,... Wenn das Chart nicht von 0 ausgehend gezeichnet werden soll (AutoScale=none, Minimum=x): Step Gridlinien z.B. Werte im Bereich 25 bis 35: Differenz ist 10 2 26,28,30,32,34 z.B. Werte im Bereich 25 bis 36: Differenz ist 11 5 25,30,35 z.B. Werte im Bereich 9 bis 36: Differenz ist 27 10 10,20,30 z.B. Werte im Bereich 5 bis 40: Differenz ist 35 10 10,20,30,40 Wenn das Chart einen positiven und negativen Darstellungsbereich hat, wird als Differenz der größte Absolutwert aller Werte genutzt. Werte Step Gridlinien -10 - 10 2 ...,-6,-4,-2,0,2,4,6,... -1 - 5 1 -1,0,1,2,3,4,5 (AutoScale=both oder minimum) -5,-4,-3,-2,-1,0,1,2,3,4,5 (AutoScale=equal oder detect) Interaktivität --------------------------------------- Das LineChart kennt drei spezielle Signale: ``chart-pointer-down``, ``chart-pointer-up`` und ``chart-pointer-move``. Diese Signale stellen zwei Informationen zur Verfügung: 1. den der Entfernung nach nächsten Datenpunkt über alle Linien basierend auf dem Ursprung des Signals (``nearest``) 2. eine Liste mit einem vertikalen Querschnitt durch alle Linien: basierend auf der X-Position des Signals wird die nächste Sampleposition bestimmt, für die alle zugehörigen Datenpunkte zurückgeliefert werden (``interceptions``) Dieses Beispiel zeigt eine Action, welche bei Mausbewegungen einen Marker an den nächstliegenden Datenpunkt setzt und den Wertequerschnitt in einem separaten Balkenchart darstellt:: Beispiel 7 .. note:: neu schreiben Label Es gibt verschiedene Arten von Labels welche im LinechartWidget vorhanden sind. **Line Labels, Start- und Endlabel an Linien** Labels, die für jede Linie erzeugt werden. Üblicherweise werden diese am Beginn bzw. Ende einer Linie platziert und dienen in der Regel dazu den Anfangs- bzw. Endwert einer Linie anzuzeigen. Die Positionierung der Label kann sich am Raster des gesamten LineChartWidgets orientieren oder an einzelnen Ankerpunkten einer Linie. **X-Achsen Labels** Achsenbeschriftungen für die X-Achse. (TBD) *Anchor wie geht das?* **Y-Achsen Labels** Achsenbeschriftungen für die Y-Achse. (TBD) *Anchor wie geht das?* Properties --------------------------------------- Neben den Properties, die für alle Charts gelten (siehe Abschnitt :ref:`ref-charts-common`), hat das LineChart folgende eigene Properties: **HitDistance** (Number) *TODO* Default: ``0`` Linien: ^^^^^^ **SamplePositions** (Table *tbd*) Weist die Values Samples zu, vgl. Beispiele 3 und 4. Default: ``null`` **LineLabels** (List[String]) Liste der Elemente welche pro Linie zur Beschriftung genutzt werden. Über ein Binding auf die momentane Linie im ``Controller`` kann der Wert der aktuellen Linie als Labelbeschriftung genutzt werden. Beispiel:: Beispiel 8 *Hier fehlt das Raster, das anzeigt, wo die Labels platziert sind* Das erste Objekt in der Liste wird als Label am Start der Linie platziert, das zweite Objekt als Label am Endpunkt der Linie. Als Werte sind die jeweiligen Werte der Linie gebunden. X-Achse ^^^^^^^ **XAxisAnchors** (List[Number]) Liste mit Werten, an denen die Labels der X-Achse platziert werden. Mit dieser Property werden die X-Achsenbeschriftungen eingeschaltet. Wenn XAxisAnchors nicht gesetzt ist, weden auch keine Labels generiert. Beispiel:: Default: ``null`` **XAxisAnchorTexts** (List[String]) Liste mit Beschriftungen, die für die Labels der X-Achse genutzt werden. Beispiel:: Default: ``null`` **XAxisLabels** (List[String]) Verweis auf ein oder mehrere Templates, welche für die zu erzeugenden Labels an der X-Achse genutzt werden sollen. In diesen kann über die Property ``XAxisController`` ein Binding auf Werte der Property ``XAxisLabels`` erfolgen. Beispiel:: Default: ``null`` **XAxisController** (ChartController) Bei Initialisierung des LineCharts wird der ``XAxisController``-Property automatisch ein (leeres) ChartController-Objekt zugewiesen. Mittels Binding kann auf Werte des XAxisControllers zugegriffen werden (z.B. XAxisAnchorText). Beispiel:: Default: ``leerer Controller`` **XAxisMinimum** (Number) Minimalwert auf der X-Achse. Default: 0 **XAxisMaximum** (Number) Maximalwert auf der X-Achse. Default: 0 **XAxisAutoScale** (Symbol) Sofern diese Property auf ``true`` steht werden die minimalen/maximalen Werte und damit die Skalierung der X-Achse aus den darzustellenden Werten ermittelt. Wenn diese Property auf ``false`` steht müssen die Properties ``MinimumX`` , ``MaximumX`` gesetzt werden um die Skalierung der Achsen festzulegen. Default: ``true`` Y-Achse (angegebene Properties analog X-Achse) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **YAxisAnchors** (List[Number]) Mit dieser Property werden die Y-Achsenbeschriftungen eingeschaltet. Wenn YAxisAnchors nicht gesetzt ist, weden auch keine Labels generiert. **YAxisAnchorTexts** (List[Object]) **YAxisLabels** (List[String]) **YAxisController** (ChartController) sowie die Widget-Properties, die sich ebenfalls auf die Werte-Dimension, also die Y-Achse, beziehen: **Minimum** (Number) **Maximum** (Number) **AutoScale** (Symbol) ``detect`` (Default), ``none, minimum, maximum, both, equal`` Methoden ------------------------ *???* Signale ------------------------ **chart-pointer-down** Dieses Signal wird ausgelöst, wenn die Maus über einem Chart gedrückt wird. **chart-pointer-up** Dieses Signal wird ausgelöst, wenn die Maus über einem Chart losgelassen wird. **chart-pointer-move** Dieses Signal wird ausgelöst, wenn die Maus über einem Chart bewegt wird. weitere Beispiele ------------------------------ Beispiel eines LineCharts mit Labels, Rasterpositionen etc. :: *TODO check* > this.Controller.setTableContent($(data, "Table[0..-1;1..-1][*]"));