3. Datentypen

Section author: 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, ...

3.1. 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.

3.2. 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 Position, Größe und Form 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.

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: MediaPlayerWidget

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" />

3.3. 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 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