.. sectionauthor:: jo
.. _ref-barchart:

###############################################################################
BarChartWidget
###############################################################################

Das BarChart-Widget dient dazu, horizontale und waagrechte Balken-/Säulencharts inklusive ihrer Labels zu zeichnen, zu animieren und interaktiv zu gestalten.

Es bietet eine Vielzahl von Einstellmöglichkeiten, mit denen es an den jeweiligen Anwendungszweck angepasst werden kann.

.. note:: Als einfachsten Fall hätte ich eigentlich lieber so etwas (ohne Data), ohne Raster, mit einem Default-Element-Spacing: (jo)

::

  Beispiel 1:
  <widget name="Chart0" type="BarChart" x="20" y="20" shape="R 400 300">
    <property name="Orientation" value="up"/>
    <!-- property name="ElementMetrics" value="spacing: 10%"/ DEFAULT!!! -->
    
    <action trigger="load">
      var temp = new Object();
      temp.companyName  = ['Hans', 'Dieter', 'Peter', 'Willi'];
      temp.companyColor = ['red', 'green', 'blue', 'yellow'];
      temp.percent      = [1 , 2, 3, 4];
      this.controller.setContent (temp);
      this.Values = temp.percent;
    </action>
    
    <property name="BarTemplates" value="BarTemplate" />
    <template name="BarTemplate">
      <bind property="BackgroundColor" 
      to="Controller.current" key="companyColor" />
    </template>
  </widget>


.. note:: Stand heute ist:

Dasselbe einfache Säulenchart, das ein Data nutzt, das auf das Chart geroutet wurde::

  Beispiel 2:
  <?xml version="1.0" encoding="UTF-8"?>
  <presentation width="340" height="200">
  
    <include src="../../data/simpledata.inc.mad" />
 
    <widget name="TheChart" type="BarChart" x="20" y="20" shape="R 300 160">
      <bind property="Data" to="presentation" key="TheData"/>
      <bind property="Values" to="Controller" key="lists.percent" />
      
      <property name="VerticalRaster" value="chart:max" />
      <property name="ElementMetrics" value="spacing: 10%"/>
      
      <property name="ColumnNames" value="name;color;percent;diff;group;image"/>
      <action trigger="data" arguments="data">
        this.Controller.setTableContent(data.get("Table"));
      </action>
    
      <property name="BarTemplates" value="BarTemplate" />
      <template name="BarTemplate">
        <bind property="BackgroundColor" to="Controller.current" key="color" />
      </template>  
    </widget>
  </presentation>

Die Property ``Orientation`` beschreibt die Richtung, in die der Balken wachsen soll. ``Orientation=up`` ist demnach ein Säulenchart. In ``VerticalRaster`` ist nur ein einziger Layoutbereich mit dem Namen ``chart`` definiert, der den zur Verfügung stehenden Platz ausfüllen soll (``max``). *Diese beiden Angaben entsprechen den Defaults.* Die einzelnen Elemente (=Balken) sollen mit einem Abstand von 10% (des theoretisch für ein Element zur Verfügung stehenden Platzes) gezeichnet werden.

Das Chart nutzt ein Template für den Balken; die Farbe des Balkens ist (im Template ``BarTemplate``) an ein Datenfeld im ``Controller`` gebunden. In der Property ``LayoutConstraints`` können für das BalkenTemplate weitere Vorgaben gemacht werden: Hier wird die ``VerticalRasterPosition`` festgelegt.

Properties
---------------------------------------

Neben den Properties, die für alle Charts gelten (siehe Abschnitt :ref:`ref-charts-common`), hat das Barchart folgende:

**Orientation** (Symbol)
	Die Richtung, in die die Balken gezeichnet werden.
	
	Werte: ``up, down, left, right``
	
	Default: ``up``

**ChartAlign** (Symbol)
	Die Position, an der die Balken oder Säulen innerhalb des Charts gezeichnet werden. 
	
	Werte: ``top, bottom, left, right, center``
	
	Default: ``center``
	

**ElementMetrics** (*List(KeyValue)*: Liste aus Key-/Value-Paaren)
	Erweiterbares Objekt zur Beschreibung von Maßangaben für Chartelemente. Als ein Chartelement wird hier die zu einem Wert gehörige Kombination aus Balken und Labels aufgefasst. Möglich sind die Angaben ``before``, ``after`` und ``spacing``, die einen Bereich vor bzw. nach dem Element oder den Zwischenraum zwischen zwei Elementen beschreiben (als Pixel oder Prozentangabe).
	
	Innerhalb der Elemente können die 
	
	Ein Chart mit einer ersten Gruppe G1 mit zwei Elementen E1 und E2 und einer zweiten Gruppe G2 mit drei Elementen E3, E4 und E5 hat demnach folgende Struktur (b: before, a: after, s: spacing)::
	
		 bbb__________________________Chart______________________aaa
		    bb________G1_______aassbb_____________G2___________aa
		      b__E1__asb__E2__a      b__E3__asb__E4__asb__E5__a
	
	Spacing kann nur zwischen Elementen in derselben Gruppe stattfinden: zwischen E2 und E3 gibt es kein Element-Spacing. 
	
	Default: ``spacing: 10%;before: 0; after: 0``

**GroupMetrics** (*List(KeyValue)*: Liste aus Key-/Value-Paaren)
	Erweiterbares Objekt zur Beschreibung von Maßangaben für (Werte-)Gruppen. GroupMetrics funktionieren wie ElementMetrics.
	
	Default: ``spacing:10%;before: 0; after: 0``

**ChartMetrics** (*List(KeyValue)*: Liste aus Key-/Value-Paaren)
	Erweiterbares Objekt zur Beschreibung von Maßangaben für das gesamte Chart.
	Implementiert sind ``before`` und ``after``, die die  äußeren Abstände vor- und nach dem Chart, jeweils von links (beim Säulenchart) bzw. oben (beim Balkenchart) gesehen, als Pixel- oder Prozentangabe beschreiben.
	
	Default: ``before: 0; after: 0``

**BarMetrics** 
  
	
**ColumnNames** (List)
	Dient dazu, die Spalten einer Data-Tabelle im ``Controller`` zu benennen, was die Zuweisung von Binding-Keys erleichtert. 
	Vgl. "Controller und Binding im Chart".
	
	Beispiel::
	
		<property name="ColumnNames" value="companyName;companyColor;percent"/>

**Controller** (ChartController)
	Objekt des Charts, das Daten verwaltet und als Binding-Target dienen kann.
	Vgl. "Controller und Binding im Chart".
	
	Default: ein leeres ``ChartController``-Objekt.
	
	Nutzen Sie eine JavaScript-Aktion, um Daten zuzuweisen (z.B. mit Controller.setTableContent()), oder weisen Sie der Property Controller den Controller eines andeen Widgets zu, um Daten gemeinsam zu nutzen.

.. note:: ChartElements fallen weg.
	
	Ersatz: ElementLabels (, SubElementLabels, GroupLabels), BarTemplates

**ElementLabels (List(Strings))**
	Liste von Templatenamen, die als Labels für Elemente verwendet werden sollen.
	
	Default: leere Liste

**BarLabels (List(Strings))**
	Liste von Templatenamen, die als Labels für SubElemente verwendet werden sollen.
	
	Default: leere Liste

**GroupLabels (List(Strings))**
	Liste von Templatenamen, die als Labels für Gruppen verwendet werden sollen.
	
	Default: leere Liste

**BarTemplates (List(Strings))**
	Liste von Templatenamen, die für die Balken verwendet werden sollen.

**MinNumberOfBars** (Integer)
	Mit der Angabe von ``MinNumberOfBars`` kann das Chartlayout modifiziert werden: Die vorhandenen Elemente werden so layoutet, *als ob* es die angegebene Zahl von Elementen gäbe.
	
	Default: 0

**MaxNumberOfBars** (Integer)
	Mit der Angabe von ``MaxNumberOfBars`` werden maximal die angegebene Zahl Balken gezeichnet, d.h. die Werteliste wird für die Darstellung abgeschnitten.
	
	Default: 12
	
**ZeroLineWidth** (Number)
	Beschreibt die Liniendicke der Nullinie.
	
	Default: 0

**ZeroLineMode** (Symbol) *NYI (war auch in Core nicht implementiert?)*

**ZeroLineOffset** (Number)
	Abstand der Nulllinie vom Balken (in pos. und neg. Richtung)
	
	Default: 0


Methoden
------------------------
*???*

Signale
------------------------
*???*

Beispiele
------------------------------

... sollten etwas komplexer sein also oben! ...

Beispiel für ein Säulenchart mit Groups und Group-Labels. Hier sehen wir drei Charts, bei denen die Group-Labels an den drei möglichen Positionen stehen: body (über den Bars), header (im Header-Bereich) und groups (über beide Bereiche)

	Beispiel::
	
	  <presentation width="1050" height="680">
  
	  <property name="Title" value="Simple Bars" />
	  
	  <template name="GLab" shape="R 10 10">
		  <property name="BackgroundColor" value="red"/>
		  
		  <property name="LayoutConstraints">
			  <map>
				  <property name="HorizontalRasterPosition" value="body"/><!-- body: chart über säulen --><!-- header: vor den gruppen --><!-- group header und body zusammen -->
				  <property name="VerticalRasterPosition" value="grp"/>
				  <property name="XSource" value="raster"/>
				  <property name="YSource" value="raster"/>
				  <property name="WidthSource" value="raster"/>
				  <property name="HeightSource" value="keep"/>
				  <property name="AlignMode" value="raster"/>
				  <property name="Align" value="top-left"/>
			  </map>
		  </property>
		  
	  </template>
	  
	  <template name="GLab2" shape="R 10 10">
		  <property name="BackgroundColor" value="red"/>
		  
		  <property name="LayoutConstraints">
			  <map>
				  <property name="HorizontalRasterPosition" value="header"/><!-- body: chart über säulen --><!-- header: vor den gruppen --><!-- group header und body zusammen -->
				  <property name="VerticalRasterPosition" value="grp"/>
				  <property name="XSource" value="raster"/>
				  <property name="YSource" value="raster"/>
				  <property name="WidthSource" value="raster"/>
				  <property name="HeightSource" value="keep"/>
				  <property name="AlignMode" value="raster"/>
				  <property name="Align" value="top-left"/>
			  </map>
		  </property>
		  
	  </template>
	  
	  <template name="GLab3" shape="R 10 10">
		  <property name="BackgroundColor" value="red"/>
		  
		  <property name="LayoutConstraints">
			  <map>
				  <property name="HorizontalRasterPosition" value="group"/><!-- body: chart über säulen --><!-- header: vor den gruppen --><!-- group header und body zusammen -->
				  <property name="VerticalRasterPosition" value="grp"/>
				  <property name="XSource" value="raster"/>
				  <property name="YSource" value="raster"/>
				  <property name="WidthSource" value="raster"/>
				  <property name="HeightSource" value="keep"/>
				  <property name="AlignMode" value="raster"/>
				  <property name="Align" value="top-left"/>
			  </map>
		  </property>
		  
	  </template>
	  
	  
	  <widget name="TheChart" type="BarChart" x="20" y="20" shape="R 300 300">
		  <property name="Debug" value="false"/>
		  <property name="BorderWidth" value="1"/>
		  <property name="VerticalRaster" type="List[KeyValue]" value="grp:40, chart: max" />
		  <property name="Values" type="List[Number]" value="1,2,3,4,5,6,7"/>
		  <property name="GroupMetrics" value="spacing: 20,header: false"/>
		  <property name="Orientation" value="up"/>
		  <property name="Groups" type="List[String]" value="A,,,B,,,"/>
		  
		  <property name="GroupLabels" value="[@GLab]"/>
  
	  </widget>
	  
	  <widget name="TheChart2" type="BarChart" x="360" y="20" shape="R 300 300">
		  <property name="Debug" value="false"/>
		  <property name="BorderWidth" value="1"/>
		  <property name="VerticalRaster" type="List[KeyValue]" value="grp:40, chart: max" />
		  <property name="Values" type="List[Number]" value="1,2,3,4,5,6,7"/>
		  <property name="GroupMetrics" value="spacing: 20,header: true"/>
		  <property name="Orientation" value="up"/>
		  <property name="Groups" type="List[String]" value="A,,,B,,,"/>
		  
		  <property name="GroupLabels" value="[@GLab2]"/>
  
	  </widget>
	  
	  <widget name="TheChart3" type="BarChart" x="700" y="20" shape="R 300 300">
		  <property name="Debug" value="false"/>
		  <property name="BorderWidth" value="1"/>
		  <property name="VerticalRaster" type="List[KeyValue]" value="grp:40, chart: max" />
		  <property name="Values" type="List[Number]" value="1,2,3,4,5,6,7"/>
		  <property name="GroupMetrics" value="spacing: 20,header: true"/>
		  <property name="Orientation" value="up"/>
		  <property name="Groups" type="List[String]" value="A,,,B,,,"/>
		  
		  <property name="GroupLabels" value="[@GLab3]"/>
  
	  </widget>
	  
	  <widget type="Text" x="50" y="350" shape="R 80 22">
		  <property name="Text" value="Header"/>
	  </widget>
  
	  <widget type="Text" x="120" y="350" shape="R 30 22">
		  <property name="BorderWidth" value="1"/>
		  <property name="Padding" value="2"/>
		  <property name="Interactive" value="true"/>
		  <property name="Text">on</property>
		  <action trigger="pointer-up">
			  this.parent.TheChart.GroupMetrics = $$("List[KeyValue]", "spacing: 20,header: true");
			  this.parent.TheChart2.GroupMetrics = $$("List[KeyValue]", "spacing: 20,header: true");
			  this.parent.TheChart3.GroupMetrics = $$("List[KeyValue]", "spacing: 20,header: true");
		  </action>
	  </widget>
	  
	  <widget type="Text" x="170" y="350" shape="R 30 22">
		  <property name="BorderWidth" value="1"/>
		  <property name="Padding" value="2"/>
		  <property name="Interactive" value="true"/>
		  <property name="Text">off</property>
		  <action trigger="pointer-up">
			  this.parent.TheChart.GroupMetrics = $$("List[KeyValue]", "spacing: 20,header: false");
			  this.parent.TheChart2.GroupMetrics = $$("List[KeyValue]", "spacing: 20,header: false");
			  this.parent.TheChart3.GroupMetrics = $$("List[KeyValue]", "spacing: 20,header: false");
		  </action>
	  </widget>
	  
	  
	  <widget type="Text" x="50" y="380" shape="R 80 22">
		  <property name="Text" value="Groups"/>
	  </widget>
	  
	  <widget type="Text" x="120" y="380" shape="R 60 22">
		  <property name="BorderWidth" value="1"/>
		  <property name="Padding" value="2"/>
		  <property name="Interactive" value="true"/>
		  <property name="Text">2 Groups</property>
		  <action trigger="pointer-up">
			  this.parent.TheChart.Groups = $$("List[String]", "A,,,B,,,");
			  this.parent.TheChart2.Groups = $$("List[String]", "A,,,B,,,");
			  this.parent.TheChart3.Groups = $$("List[String]", "A,,,B,,,");
		  </action>
	  </widget>
	  
	  <widget type="Text" x="190" y="380" shape="R 60 22">
		  <property name="BorderWidth" value="1"/>
		  <property name="Padding" value="2"/>
		  <property name="Interactive" value="true"/>
		  <property name="Text">3 Groups</property>
		  <action trigger="pointer-up">
			  this.parent.TheChart.Groups = $$("List[String]", "A,,B,,C,");
			  this.parent.TheChart2.Groups = $$("List[String]", "A,,B,,C,");
			  this.parent.TheChart3.Groups = $$("List[String]", "A,,B,,C,");
		  </action>
	  </widget>
	  
	  <widget type="Text" x="260" y="380" shape="R 60 22">
		  <property name="BorderWidth" value="1"/>
		  <property name="Padding" value="2"/>
		  <property name="Interactive" value="true"/>
		  <property name="Text">0 Groups</property>
		  <action trigger="pointer-up">
			  this.parent.TheChart.Groups = null;
			  this.parent.TheChart2.Groups = null;
			  this.parent.TheChart3.Groups = null;
		  </action>
	  </widget>
	  
	  
  </presentation>