.. _ref-types:

###############################################################################
Datentypen
###############################################################################

.. sectionauthor:: jo
.. note:: XXXXXXXXXXXXXXX Status 12.10.2010: verbindlich. XXXXXXXXXXXXXXXXXXXX

   fehlt: JS-Beispiel für myList.iterator()
   
   TODO: Javascript und Zugriffe für Compound Datatypes: Ist-Zustand dokumentieren
   
   * Ergänzungen JavaScript-Syntax
   * Test, ob die XML- und JavaScript-Konstrukte funktionieren (z.B. define name="xxx" type="Table[String]" value="[[a,b,c],[d,e,f]]"></define>)
   * Unittests ergänzen
   * Fehlende Types ergänzen (sh. mp.types): Time, ...




Datentypen in XML und JavaScript
================================================================================

Alle Datentypen werden im XML als Strings repräsentiert. Sie in den richtigen Datentyp zu wandeln, übernehmen in MaongoMP sogenannte Transcoder.

Im XML ist dieser Vorgang automatisch, häufig ist noch nicht einmal eine ``type``-Angabe nötig.
So können Property-Werte ohne Type gesetzt werden, da das Widget "weiß", von welchem Typ seine Properties sind. Auch Defines können ohne ``type``-Angabe auskommen und speichern so zunächst einen Wert vom Typ String. Wird er einer Property zugewiesen, so wird er automatisch transcodiert. 

In JavaScript kann ein Objekt eines bestimmten Typs mit folgender Syntax erzeugt werden::

  Type.newInteger(42)             // ohne Transcoding
  Type.newRectangle(100,100)  
  Type.newShape("R 0,0,100,100")  // Ausnahme; Transcoding nötig //Geht nicht, CF
  etc.

Ebenfalls möglich ist die folgende Schreibweise, die immer zwei String-Argumente erwartet und wie die Formulierung im XML immer mit einem Transcoding-Vorgang einhergeht::

  $$("Integer", "42")
  $$("Rectangle", "0,0,100,100") 
  $$("Shape", "R 0,0,100,100")
  etc.


Auflistung der Datentypen
================================================================================

**Object**

  Ein generisches Objekt. Alle weiteren Datentypen erben von Object; für den Anwender nicht direkt zu nutzen.
  Nicht zu verwechseln mit dem ``<object>``-Tag, der immer eine ``type``-Angabe erfordert und somit für 
  ein spezifisches (typisiertes) Objekt steht.

**Integer**

  Eine generische Ganzzahl, positiv oder negativ, mindestens 32 Bit breit.
  
  XML::
  
    <... type="Integer" value="42"/>
      
**Number**

  Eine generische Fließkommazahl, positiv oder negativ, mindestens 32 Bit breit.
  
  XML::
  
    <... type="Number" value="42.23"/> 

**Decimal**

  In Java als BigDecimal implementiert. Andere Plattformen nutzen u.U. Fließkommazahlen.

  XML::
  
    <... type="Decimal" value="42.5"/> 

**Boolean**

  Folgende Schreibweisen sind gültig: ``true``, ``false``.

**String**

  Ein generischer String.

**Symbol**

  Spezieller Datentyp z.B. für Properties, bei denen nur bestimmte Begriffe
  als Werte erlaubt sind. 
  
  Konvertierbarkeit: Alle Typen die nach String konvertierbar sind, können auch nach Symbol konvertiert werden.
  
  XML::
    
    <... type="Symbol" value="top-left"/>

**Date**

  Datentyp für Datums- und Zeitangaben
  
  XML::
  
    <... type="Date" value="2010-01-01" />
    <... type="Date" value="2010-01" />
    <... type="Date" value="2010" />
    <... type="Date" value="2010-01-01 00:15:24" />

**Point**

  Eine Koordinate auf einer Fläche. Die X- und Y-Werte der Koordinate werden
  als zwei durch Komma oder Whitespace getrennte Numbers angegeben.

  XML::
    
    <... type="Point" value="10.2,15.4"/>

**Padding**

  Padding beschreibt den Abstand zweier ineinanderligender Objekte an den
  vier Seiten oben, unten, rechts und links. Padding kann mit einer Wertangabe (alle Abstände gleich), 
  mit zwei (oben/unten und links/recht) oder vier (oben, rechts, unten, links) Werten 
  definiert werden:
  
  XML::
    
    <... type="Padding" value="23.4"/>
    <... type="Padding" value="23.4,42.3"/>
    <... type="Padding" value="10,15,12,5"/>
    
  Die Widget-Property Padding wird im Abschnitt :ref:`ref-possize` beschrieben.
    

**Color**

  Der Datentyp Color beschreibt eine Farbe mit den Komponenten Rot, Grün, Blau und Alpha. Die Alphawerte beschreiben die Opazität der Farbe (entsprechend der Verwendung in CSS); der Wert 0 weist die Farbe als vollständig transparent aus, der Wert 1 (oder 255 / FF) als vollständig opak. Ist kein Alpha-Anteil angegeben, so gilt die Farbe stets als vollständig opak.
  
  **Farbangaben mit Farbnamen**
  
  Maongo unterstützt die 16 Farbnamen der VGA-Palette sowie die 
  Bezeichner "orange" und "transparent". Die Farbnamen werden klein geschrieben, 
  die Schreibweise ist case-sensitiv.::
  
    * black   = #000000  
    * silver  = #C0C0C0 
    * gray    = #808080 
    * white   = #FFFFFF 
    * maroon  = #800000 
    * red     = #FF0000 
    * purple  = #800080 
    * fuchsia = #FF00FF
    * green   = #008000
    * lime    = #00FF00 
    * olive   = #808000 
    * yellow  = #FFFF00 
    * navy    = #000080 
    * blue    = #0000FF 
    * teal    = #008080 
    * aqua    = #00FFFF 
    * orange  = #ffa500 
    * transparent = #000000/00
  
  **Hexadezimale Farbangaben in HTML-Schreibweise**
  
  Farbwerte können hexadezimal nach dem Langschema #RRGGBB oder dem 
  Kurzschema #RGB angegeben werden. Bei der Kurzschreibweise werden die 
  Angaben intern verdoppelt. "#FCF" steht dann für "#FFCCFF".
  Die hexadezimale Schreibweise ist case-insensitiv.
  ::
  
    #RRGGBB
    #RGB
  
  **Hexadezimale Farbangaben mit Alpha**
  
  
  Folgt nach der Hexadezimalzahl ein Slash "/", werden die beiden nächsten 
  hexadezimalen Ziffern als Angaben für den Alphawert gewertet. 
  Die Kurzschreibweise #RGB/A ist ebenfalls möglich. Die hexadezimale Schreibweise 
  ist case-insensitiv::
  
    #RRGGBB/AA oder #RGB/A
  
  Beispiele::
  
    #008000                Grün, 100% opak ( == #008000/FF )
    #008000/00             Grün, 100% transparent
    #008000/FF             Grün, 100% opak
    #000000/00 = "transparent"
    
  **Numerische Farbangaben nach CSS mit RGB(A)**
  
  Eine weitere Möglichkeit, Farben anzugeben, ist die rgba-Notation. Die Werte werden numerisch von 0 bis 255 angegeben. 
  
  Der Wert "a" definiert die Opazität, ist fakultativ und wird von 0 bis 1 angegeben, wobei 1 für 100 % Deckkraft steht::
  
    rgb(0,255,0)           Grün, 100% opak
    rgba(0,255,0,1)        Grün, 100% opak
    rgba(0,0,0,0) = "transparent"

**File**

  Der Datentyp ``File`` erwartet einen String (ohne Protokoll) für eine Pfadangabe im lokalen Filesystem. Die Pfadangabe muss absolut formuliert sein. Es findet keine Übersetzung der Plattform-Spezifika statt.

**URL**

  Der Datentyp ``URL`` erwartet einen URI (mit Protokoll http oder file, absolut oder relativ) als String.

.. _ref-types-image:

**Image** 

  Der Datentyp ``Image`` erwartet einen Lademodus und einen URL (mit Protokoll http oder file, absolut oder relativ) als String in
  eckigen Klammern.
  
  Gleichbedeutend sind::
  
    <property name="Texture" type="Image" value="http://my.server.com/images/picture.png" />
    <property name="Texture" type="Image" value="[lazy http://my.server.com/images/picture.png]" />

  Als Angaben für den Lademodus sind erlaubt:
  
  * ``lazy`` - der Ladevorgang wird angestossen, sobald das Bild verwendet wird
  * ``preload`` - Das Bild wird geladen, bevor die Presentation gestartet wird
  * ``embed`` - Das Bild wird - wenn auf der jeweiligen Plattform möglich - mit in die Presentation integriert. Es wird geladen, bevor die Presentation gestartet wird
  
  Alternativ kann auch nur der URL angegeben werden, der Lademodus ist dann implizit ``lazy``.

**Media**

  Der Datentyp ``Media`` erwartet eine Map zur Definition der verschiedenen Eigenschaften.
  
  Einfache Syntax::
	
	<property name="Source" type="Media" value="URL:http://meinserver.de/v1.mp4"/>
  
  Um detaillierte Informationen zu einer Source liefern zu können, kann auch eine explizit definierte Map übergeben werden
 
  Beispiel einer RTMP-Source::

		  <property name="Source">
		    <map>
		      <entry name="RTMPServerPath">rtmp://mediaserver.de/_definst_</entry>
		      <entry name="RTMPMediaPath" >rtmp_stream_flv</entry>
		      <entry name="ConnectionType" >rtmp</entry>
		      <entry name="UseFCSubscribe">true</entry>
		    </map>
		  </property>
  
  Zur Beschreibung des Mediums können die folgenden Einträge in der Map übergeben werden:
  
  **URL** (String)
     Die Url von der das Medium wiedergegeben werden soll. Es können HTTP, RTMP oder RTMPT-Quellen angegeben werden. Bei Angabe einer HTTP-Quelle ist die Angabe der Property ``MediaPath`` nicht notwendig. Für RTMP- bzw. RTMPT-Quellen ist hier die URL des Media-Servers anzugeben. Die Angabe des wiederzugebenden Mediums erfolgt in der Property ``MediaPath``
	
     Hinweis:: 
     
        RTMP-Quellen werden derzeit nur in der Flash-Ausspielung unterstützt. RTMPT-Quellen werden noch nicht unterstützt.


  **MediaPath** (String)
      Sofern RTMP/RTMPT-Quellen genutzt werden sollen, muss in dieser Property der für den Verbindungsaufbau notwendige Pfad zur tatsächlichen Medienquelle angegeben werden.
  
  **ConnectionType** (String)
     Art der Verbindung die hergestellt werden soll. 
  
     Default: ``http``
     
     Values: ``http``, ``rtmp``, ``rtmpt``
  
  **UseFCSubscribe** (String)
     Soll für die Verbindung mit einem Media-Server über RTMP/RTMPT ein Subscribe Aufruf geschickt werden? Dies ist bei bestimmten Media-Servern notwendig um Medien abspielen zu können.
     
     Default: ``false``
     
     Values: ``true``, ``false``
  
  siehe: :ref:`ref-mediaplayer`
  

**Shape**

  ``Shape`` ist ein Interface, das durch eine Reihe von Klassen (``Rectangle, Shape, Path, Polygon, Circle, Ellipse``) implementiert wird.
  
  Properties, die Werte vom Datentyp ``Shape`` erwarten, können mit allen vom Interface abgeleiteten Datentypen beschickt werden.

**Rectangle**

  Der Typ ``Rectangle`` erlaubt die Definition von Rechtecken in der folgenden Form::
  
   "(px py )w h"
   "0 0 100 100"
   "100 100"
   "10 10 100 100"
   "-10 -10 100 100"
   Verwendung: <property name="Shape" type="Rectangle" value="0 0 100 100" />
   oder <widget rect="0 0 100 100" />

  Die Angabe ``px py`` bezeichnet den Punkt, an dem die linke obere Ecke des Rechtecks im Koordinatensystem des Widgets gezeichnet wird; sie ist optional. Je nach Kontext kann die Angabe von negativen Werten in ``px py`` invalide sein (zum Beispiel bei der Maongo-Property ``InnerShape``). 

  w und h geben die Breite und Höhe des Shapes in Pixeln an.

  Eine alternative Schreibweise für Rectangle ist, den Typ ``Shape`` anzugeben und den Wert als String so zu formulieren::
  
   "R (px py )w h"
   "R 0 0 100 100"
   Verwendung: <property name="Shape" type="Shape" value="R 0 0 100 100" />


**Path**

  Freigeformte Shapes werden in SVG-Pfadsyntax angegeben und sind vom Typ ``Path``. Der folgende SVG-Pfad::
  
   <path d="M 20 20 L 18 22 C 24 28 14 25 10 40 Q 20 45 15.33 60" />
  
  wird als Shape-Beschreibung so genutzt::
  
   <property name="Shape" type="Path" value="M 20,20 L 18,22 C 24,28 14,25 10,40 Q 20,45 15.33,60" />
   
  MaongoMP unterstützt alle in der SVG 1.1-Spezifikation für Pfade definierten Elemente (http://www.w3.org/TR/SVG11/paths.html). Wo eine Ausspielplattform für bestimmte Kurventypen keine native Unterstützung bietet, werden diese näherungsweise gezeichnet. 

**Polygon, Kreis, Ellipse**

  Die SVG-Syntax für Polygone, Kreise und Ellipsen können bei Angabe des entsprechenden Typs verwendet werden::
  
   SVG: <polygon points="100 100 100 200 150 200" />
   Verwendung: <property name="Shape" type="Polygon" value="<x y> <x y>..." />
   <property name="Shape" type="Polygon" value="100,100 100,200 150,200" />
   alternative Schreibweise:
   <property name="Shape" type="Shape" value="P 100,100 100,200 150,200" />
  
   SVG: <circle cx="100" cy="100" r="50" />
   Verwendung: <property name="Shape" type="Circle" value="<cx> <cy> <r>" />
   <property name="Shape" type="Circle" value="100 100 50" />
   alternative Schreibweise:
   <property name="Shape" type="Shape" value="O 100 100 50" />
  
   SVG: <ellipse cx="100" cy="100" rx="50" ry="20" />
   Verwendung: <property name="Shape" type="Ellipse" value="<cx> <cy> <rx> <ry>" />
   <property name="Shape" type="Ellipse" value="100 100 50 20" />
   alternative Schreibweise:
   <property name="Shape" type="Shape" value="E 100 100 50 20" />
  
  Maongo akzeptiert alle SVG-tauglichen Schreibweisen für die Shape-Werte. Werte können beispielsweise durch Leerzeichen, Komma oder auch gemischt getrennt werden::
  
   <property name="Shape" type="Polygon" value="100 100 100 200 150 200" />
   <property name="Shape" type="Polygon" value="100,100 100,200 150,200" />
   <property name="Shape" type="Polygon" value="100,100,100,200,150,200" />
   
  

Compound Datatypes
================================================================================

**List**
  Im XML des MAD-Dokuments können auch (ein- und mehrdimensionale) Listen definiert werden. Das Trennzeichen zwischen Listenitems ist stets das Semikolon ``;``. Im ``type``-Attribut kann die Liste typisiert werden. Ist kein Typ angegeben, so wird angenommen, dass die Listenitems Strings sind::
  
    <... type="List[Number]" value="3,4,3.5" />
    <... type="List[String]" value="Hans,Dieter,Peter" />
    <... type="List" value="Hans,Dieter,Peter" />
  
  Ein besonderer Fall ist der Typ ``List[KeyValue]``, der beispielsweise zur Definition eines LayoutRasters benutzt wird::
  
    <... type="List[KeyValue]" value="fl: 10, s1: 4, chart: max, ll: 0" />
  
  Jedes Listenitem besteht hier aus einem ``key`` (``fl``) und einem Wert (``10``), getrennt durch Doppelpunkt.
  
  Listen können auch in einer expliziten Syntax beschrieben werden::
  
    <list>
      <item type="Number">3</item>
      <item type="Number">4</item>
      <item type="Number">3.5</item>
    </list>
    <list>
      <item>Hans</item>
      <item>Dieter</item>
      <item>Peter</item>
    </list>
  
  Eine zweidimensionale Liste in verschiedenen Syntax-Varianten::
  
    <property name="Values">
      <list>
        <list>
      <item type="Number">3</item>
        <item type="Number">4</item>
        <item type="Number">3.5</item>
      </list>
      <list>
      <item type="Number">5</item>
      <item type="Number">6</item>
      <item type="Number">6</item>
      </list>
      </list>
    </property>
  
    oder:
  
    <property name="Values">  
      <list>
        <item type="List[Number]">3,4,3.5</item>
        <item type="List[Number]">5,6,6</item>
      </list>
    </property>
  
    oder:
    
    <property name="Values" type="List[List[Number]]"  value="[[3,4,3.5],[5,6,6]]" /> //Geht nicht, CF
    
  
  Beispiele für Listenzugriffe mit Lookups::
  
    <define name="one" type="Number" value="1"/>
    <define name="two" type="Number" value="2"/>
    <define name="examplelist" type="List[Number]" value="[1,2,3]"/> 
    <define name="examplelist" type="List[Number]" value="1,2,3"/> 
  
    <property type="List" value="[@one,@two]"/>
    ( ==> [1,2] )
    <property type="List[Number]" value="@examplelist"/> 
    ( ==> [1,2,3] )
    <property type="List" value="[@examplelist]" />
    ( ==> [[1,2,3]] )
    <property type="List[Number]" value="[@examplelist,2,@examplelist]"/>
    ( ==> [[1,2,3],2,[1,2,3]] )
    <property type="List" value="[@examplelist,2,@examplelist]"/>
    ( ==> [[1,2,3],"2",[1,2,3]] - die Elemente der äußeren Liste werden wo nötig als String typisiert )
    <property type="List[Number]" value="@examplelist,2,@examplelist"/>
    ( ==> null - eckige Klammern nötig ) //CF: Bzw. wirft eine NullPointerException und macht damit die mad unbrauchbar.
    
  **Zugriff auf Lists:**
  
  **JavaScript:**
  
  Neue (leere) Liste erzeugen::
  
    var myList = Type.newList();
    
    // auch: var myList = $$("List");
  
  Methoden von List nutzen::
  
    myList.add(17);
    trace(myList.size());
    // 1
    myList.add(21);
    trace(myList.get(0));
    // 17
    myList.remove(0);
    trace(myList.get(0));
    // 21
    
  JavaScript-Arrays können in Listen umgewandelt werden *NYI*::
  
    var jsArray = [1, "hans", 13];
    var myList = Type.newListFromArray(jsArray); //CF geht im moment nicht. Bug. Also schon implemented. So halb:)
    
    trace(myList.size());
    // 3
    trace(myList.get(0));
    // 1
    trace(myList.get(1));
    // "hans"

**Map**
  Maps sind ungeordnete Sammlungen von Key/Value-Paaren. Der Zugriff erfolgt nur über den Key; die Einträge haben keine spezifische Reihenfolge. Entries sind typisiert.
  
  XML-Struktur::
  	<define name="myMap">
	    <map>
			<entry name="aKey"  value="aValue"/>
			<entry name="aKey2"  value="aValue2"/>
		</map>
  	</define>
  
  Zugriff auf Maps::
  
    fehlt
  
  JavaScript::
  	Eine Map wird als maongo.core.ValueMap zurückgeliefert. Auf diese Map kann man mit map.get("key") oder map.getValueForKey("key") zugreiffen.
  	
  	var myMap = $(this,"mapDefinition");
  	trace(myMap.getValueForKey("aKey"));  // >> aValue
    
  

**Table**
  Ein Table ist eine geordnete Sammlung von ``Rows``, die wiederum eine geordnete Sammlung von (typisierten) Cells enthalten.
	//CF: Table kann nicht definiert werden
  XMLStruktur::
  
    <table>
      <row>
        <cell>
  
  Zugriff auf Tables::
  
    fehlt
  
  JavaScript::
  
    fehlt
  

**Textformat**
  
  XML-Struktur::
  
    <textformat>
      <property>
  
  JavaScript::
  
    fehlt
  
  Textformate können nicht in JavaScript modifiziert werden.
  
  Vgl. den Abschnitt :ref:`ref-textwidget`
    

**Data**

  Ein Data-Objekt ist eine Sammlung von ``Property``, ``Table``, ``Map`` und ``List``-Objekten.

  XML-Struktur::
  
    <data>
      <property />
      <table />
      <map />
      <list />
    </data>
   
  Zugriff auf Data::
  
    fehlt
  
  JavaScript::
  
    fehlt
    
**Transmission**

  Eine Transmission ist eine Sammlung von ``Data``-Objekten.
  
  XML-Struktur::
  
    <transmission>
      <data />
      <data />
    </transmission>
    
  JavaScript::
  
    fehlt