Vorsicht

Dies ist die Dokumentation des aktuellen Entwicklungszweigs der CometVisu. Es besteht daher die Möglichkeit, dass einige der hier beschriebenen Features mit dem aktuellsten Release der CometVisu nicht genutzt werden können.

Die RST-Syntax

Überschriften

Überschriften werden in RST durch „unterstreichen“ des Textes mit bestimmten Sonderzeichen definiert. Zu beachten ist hier, das die Sonderzeichen mindestens genauso lang sind wie der Text selbst. Auch wenn die RST-Syntax bei der Benutzung der Sonderzeichen relativ tolerant ist, wird für die CometVisu Dokumentation folgende Definition festgelegt.

######################
Komplette Teilbereiche
######################

*******
Kapitel
*******

Sektionen
=========

Unter-Sektionen
---------------

Unter-Unter-Sektionen
^^^^^^^^^^^^^^^^^^^^^

Paragraphen
"""""""""""

Die kompletten Teilbereiche, sind den Teilen Api, Benutzerhandbuch und Tutorials vorbehalten und dürfen ansonsten innerhalb der Dokumentation nicht vorkommen, alle anderen können mit bedacht verwendet werden.

Inline Markup

Soll der Text in der Dokumentation besonders formatiert (z.B. fett, kursiv, usw.) oder Referenzen / Links eingebaut werden benötigt man eine spezielle Syntax innerhalb des Textes.

Zur Formatierung eines Textes, wird der Text ebenfalls von Sonderzeichen umrahmt, so kann man ein Wort z.B. fett formatieren indem man in mit zwei Sternchen umfasst (**fetter Text**), weitere Möglichkeiten sind.

Fett: **fetter Text** => fetter Text
Kursiv: *kursiver Text* => kursiver Text
Code-Beispiele: ``Code im Text`` => Code im Text

Listen

Für unnummerierte Listen wird jede Zeile mit * gestartet, bei nummerierten mit #.. Mit entsprechender Einrückung der Zeilen sind auch verschachtelte Listen möglich.

Links und Referenzen

Die Grundsätzliche Syntax von Links enthält einen Title und den Link selbst in folgender Struktur: `Titel des Links <URL des Links>`__. Natürlich kann man auch auf andere Dokumente innerhalb der Dokumentation verweisen: :doc:`Titel <relativer/pfad/zum/document>`. Zu beachten ist hierbei, dass man die .rst Dateiendung weglassen muss. Möchte man also ein Dokument namens dok.rst im Unterverzeichnis test verlinkten, sieht das so aus: :doc:`test/dok`. Der Titel des Links ist optional, wird er weggelassen, wird der Seitentitel des verlinkten Dokuments als Titel benutzt (also die Überschrift auf der höchsten Ebene innerhalb des Dokuments).

Direktiven

Für Dinge die über reinen Text hinaus gehen (z.B. Bilder, Hinweise, Warnungen, usw.) werden Direktiven verwendet. Diese dürfen im Gegensatz zum bereits behandelten inline Markup nicht in der selben Zeile wie der „normale“ Text stehen sondern benötigen eine Leerzeile vor und hinter der Direktive. Direktiven bestehen aus einem Namen, Parametern Optionen und dem Inhalt und sind immer nach folgendem Prinzip aufgebaut:

.. <name>:: <parameter1> <parameter2> ...
     :<option1>: <optionswert1>
     :<option2>: <optionswert2>
     ....

     <Inhalt der Direktive>

Eine Direktive startet immer mit 2 Punkten gefolgt von einem Leerzeichen. Darauf folgt der Name und dann direkt, ohne Leerzeichen 2 Doppelpunkte. Weiterhin zu beachten ist, dass die Optionen durch Doppelpunkte eingefasst und durch eine Leerzeile vom Inhalt getrennt sind, außerdem sind Optionen und Inhalt eingerückt.

Das einzige, was zwingend erforderlich ist, ist der Name. Parameter, Optionen und Inhalt sind optional und unterscheiden sich in Menge und vorhandensein von Direktive zu Direktive. Im folgenden werden nun die wichtigsten Direktiven vorgestellt.

Text-Blöcke

Einfache Direktiven, mit denen ein farblich hervorgehobener Textblock mit vorgegebenem Titel erstellt werden können, um damit Hinweise, Informationen, Warnungen usw. zu definieren. Diese Direktiven haben keine Parameter und Optionen, lediglich einen Inhalt.

Mögliche Textblöcke sind: attention, caution, danger, error, hint, important, note, tip, warning. Möchte man den Leser also z.B. auf etwas wichtiges Hinweisen, kann man folgendes schreiben.

.. IMPORTANT::

    Dies ist ein wichtiger Hinweis.

Was dann so formatiert wird:

Wichtig

Dies ist ein wichtiger Hinweis.

Bilder

Bilder werden mit der figure-Direktive eingebunden. Es gibt zwar auch eine image-Direktive, aber die figure-Direktive erlaubt komplexe Bildunterschriften.

.. figure:: <pfad-zum-bild>

    Dies ist die Bildunterschift

Die komplette Syntax dieser Direktive kann in der offiziellen Dokumentation nachgelesen werden.

Eigene Direktiven

Neben den vorhandenen Sphinx/Docutils Direktiven werden in der CometVisu Dokumentation auch einige Direktiven genutzt, die dabei helfen, die Dokumentation einfacher auf einem aktuellen Stand zu halten. Folgende Direktiven werden zur Zeit unterstützt:

Name	Beschreibung
widget-example	Ermöglicht Beispielcode für Widgets aus dem automatisch Screenshots erstellt werden kann.
parameter-information	Zeigt alle Attribute eines Widgets mit erlaubten Werten und kurzer Erklärung als Tabelle an.
elements-information	Zeigt alle erlaubten Unter-Elemente eines Widgets inkl. deren Attributen als Tabelle an.
api-doc	Bindet Informationen aus der Source-Code Dokumentation ein (@author und @since)
replaces	Hiermit lässt sich festlegen, welche Seiten des alten Wikis diese Seite ersetzt

Die widget-example Direktive

Die widget-example Direktive erlaubt Beispiel-Code einer CometVisu config aus der später vollautomatisch einer oder mehrere Screenshots generiert werden und zusammen mit dem Beispiel-Code in die Dokumentation eingebunden werden.

Das folgende Beispiel:

.. widget-example::

    <settings>
        <screenshot name="switch_complete">
            <caption>Switch mit mapping + styling</caption>
            <data address="1/4/0">1</data>
        </screenshot>
    </settings>
    <meta>
        <mappings>
            <mapping name="OnOff">
                <entry value="0">Aus</entry>
                <entry value="1">An</entry>
            </mapping>
        </mappings>
        <stylings>
            <styling name="RedGreen">
                <entry value="1">red</entry>
                <entry value="0">green</entry>
            </styling>
        </stylings>
    </meta>
    <switch on_value="1" off_value="0" mapping="OnOff" styling="RedGreen" bind_click_to_widget="true">
      <label>Kanal 1<icon name="control_on_off"/></label>
      <address transform="DPT:1.001" mode="readwrite">1/1/0</address>
      <address transform="DPT:1.001" mode="read">1/4/0</address>
    </switch>

erzeugt diesen Eintrag in der Dokumentation:

...
<meta>
    <mappings>
        <mapping name="OnOff">
            <entry value="0">Aus</entry>
            <entry value="1">An</entry>
        </mapping>
    </mappings>
    <stylings>
        <styling name="RedGreen">
            <entry value="1">red</entry>
            <entry value="0">green</entry>
        </styling>
    </stylings>
</meta>
...
<switch on_value="1" off_value="0" mapping="OnOff" styling="RedGreen" bind_click_to_widget="true">
  <label>Kanal 1<icon name="control_on_off"/></label>
  <address transform="DPT:1.001" mode="readwrite">1/1/0</address>
  <address transform="DPT:1.001" mode="read">1/4/0</address>
</switch>

Der Inhalt der Direktive orientiert sich am Aufbau der normalen CometVisu Konfigurationsdatei und ist ebenfalls ein XML-Dokument. Er besteht im Wesentlichen aus 3 Bereichen:

<settings> Hier werden die Screenshots und Untertitel definiert.
<meta> Hier ist alles erlaubt, was auch innerhalb des <meta>-Elements der Konfigurationsdatei erlaubt ist (z.B. Laden von Plugins, Definition von Mappings, Stylings usw.)
Alles andere Alles was nicht innerhalb eines <settings> oder <meta>-Elements ist, wird als Beispielcode interpretiert. Hier ist also alles erlaubt, was innerhalb eines <page>-Elements der Konfigurationsdatei erlaubt ist (z.B. Widgets, Groups, usw.)

Die Bereiche 1. und 2. sind optional und können auch weggelassen werden, wenn man also z.B. nur 1 Screenshot vom Beispielcode ohne Untertitel benötigt kann der <settings>-Teil auch weggelassen werden.

Darüber hinaus gibt es noch diverse Optionen mit denen das Aussehen des Beispiel-Codes und des zu gehörigen Screenshots beeinflusst werden können

linenos: Wenn angegeben, wird der Beispielcode mit Zeilennummern angegeben
lineno-start: Zahl bei der die Zeilennummern starten sollen (Default: 1)
scale: Prozentangabe mit der der Screenshot verkleinert werden kann (Default: 100)
hide-source: true oder false. (Default: false), zeigt den Beispielcode nicht an wenn true
editor: attributes oder elements. Macht einen Screenshot vom Beispielcode im Editor und nicht vom Widget selbst
align: left, center oder right. Definiert die Position des Screenshots (Default: left)

Ein vollständiges Beispiel mit allen Optionen:

.. widget-example::
    :linenos:
    :linenos-start: 1
    :scale: 75
    :hide-source: true
    :editor: attributes
    :align: center

    ....

Der <settings>-Bereich

Dieser Bereich wird definiert durch das <settings>-Element und dieses kann durch Attribute und Unterelemente verfeinert werden.

Element	Attribut
	Name	Inhalt	Beschreibung
<settings>	design	Name eines Designs	In welchem Design der Screenshot aufgenommen werden soll (Default: metal)
	selector	Css-Selector	Definiert den Bereich des Screenshots
	sleep	Zahl	Initiale Wartezeit in ms bevor der Screenshot aufgenommen wird
<settings> <caption>		#text	Untertitel des Beispielcodes
<settings> <screenshot>	name	Text	Dateiname des Screenshots
	clickpath	CSS-Selector	CSS-Pfad zu einem Element, das angeklickt werden soll vor dem Screenshot
	waitfor	CSS-Selector	CSS-Pfad zu einem Element, das sichtbar sein soll vor dem Screenshot
	sleep	Zahl	Wartezeit zwischen Senden der Daten und Screenshot
<settings> <screenshot> <data>	address	Gruppenadresse	Sende Daten an diese Adresse bevor der Screenshot gemacht wird
	type	float oder int	Falls echte Zahlenwerte gesendet werden müssen
	#text	Text	Inhalt der Daten die gesendet werden sollen

Die parameter-information Direktive

Diese Direktive erzeugt automatisch eine Tabellenübersicht mit den Attributen des Widgets. Diese Daten werden aus der Schema-Definition (visu_config.xsd) ausgelesen. Diese Direktive hat keine Optionen und keinen Inhalt und nur einen Parameter der den Widget-Namen enthält.

Dieses Beispiel erzeugt die Attribut-Tabelle für das Switch-Widget.

.. parameter-information:: switch

Element	Attribut
	Name	Inhalt	Beschreibung
switch	styling	Text	Ändert die Farbe des angezeigten Wertes abhängig vom Wert selbst. Siehe auch Styling
	mapping	Text	Ordnet den Werten vom Bus andere Werte, Texte oder Symbole zur Anzeige zu. Siehe auch Mapping
	on_value	Text	Wert für den An-Zustand. Default ist „1“.
	off_value	Text	Wert für den Aus-Zustand. Default ist „0“.
	align	left, right oder center
	flavour	Text	Auswahl der Darstellungsvariante. Siehe auch Flavour.
	bind_click_to_widget	true oder false	Beim Aktivieren dieser Option wird die gesamte Widget Fläche als Schaltfläche genutzt
	class	Text	Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
	format	Text	Formatierung des Wertes (printf-Syntax).

Die elements-information Direktive

Diese Direktive erzeugt automatisch eine Tabellenübersicht mit den erlaubten Unter-Elementen eines Widgets. Diese Daten werden aus der Schema-Definition (visu_config.xsd) ausgelesen. Diese Direktive hat keine Optionen und keinen Inhalt und nur einen Parameter der den Widget-Namen enthält.

Dieses Beispiel erzeugt die Element-Tabelle für das Switch-Widget.

.. elements-information:: switch

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
switch layout	colspan	Zahl	Spaltenanzahl für dieses Widget.
	colspan-m	Zahl	Übersteuert die Spaltenanzahl auf mittleren (medium) Browser Größen.
	colspan-s	Zahl	Übersteuert die Spaltenanzahl auf kleinen (small) Browser Größen.
	rowspan	Zahl	Zeilenanzahl für dieses Widget.
	x	Text	Horizontale Position des Widgets auf 2D Seiten.
	x-s	Text	Horizontale Position des Widgets auf 2D Seiten auf kleinen (small) Browser Größen.
	x-m	Text	Horizontale Position des Widgets auf 2D Seiten auf mittleren (medium) Browser Größen.
	y	Text	Vertikale Position des Widgets auf 2D Seiten.
	y-s	Text	Vertikale Position des Widgets auf 2D Seiten auf kleinen (small) Browser Größen.
	y-m	Text	Vertikale Position des Widgets auf 2D Seiten auf mittleren (medium) Browser Größen.
	z	Text	Für zukünftige Anwendungen reserviert.
	width	Text	Breite des Widgets auf 2D Seiten.
	width-s	Text	Breite des Widgets auf 2D Seiten auf kleinen (small) Browser Größen.
	width-m	Text	Breite des Widgets auf 2D Seiten auf mittleren (medium) Browser Größen.
	scale	true oder false	Automatische Anpassung der Layout-Werte auf Basis der Skalierung des Backdrops ein/-ausschalten (Standardeinstellung: true).
	scale-s	true oder false	Automatische Anpassung der Layout-Werte auf Basis der Skalierung des Backdrops ein/-ausschalten auf kleinen (small) Browser Größen (Standardeinstellung: true).
	scale-m	true oder false	Automatische Anpassung der Layout-Werte auf Basis der Skalierung des Backdrops ein/-ausschalten auf mittleren (medium) Browser Größen (Standardeinstellung: true).

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
switch label icon	name	Text	Name unter dem das Icon registriert ist.
	type	Text
	flavour	Text	Auswahl der Darstellungsvariante. Siehe auch Flavour.
	color	Text	Farbe des Icon in CSS Notation (z.B. #1188FF).
	styling	Text	Ändert die Farbe des angezeigten Wertes abhängig vom Wert selbst. Siehe auch Styling
	class	Text	Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
switch label #text		Text	Text um bei dem Widget eine Beschreibung darzustellen.

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
switch address	transform	Text	Umwandlung des Bus-System Wertes um angezeigt werden zu können.
	mode	disable, read, write oder readwrite	„disable“ deaktiviert die Kommunikation, bei „read“ wird nur vom Backend gelesen, bei „write“ wird nur geschrieben und „readwrite“ wird die Adresse zum Lesen und zum Schreiben verwendet.
	variant	Text
	format-pos	Zahl	Position für Format-String wenn mehrere Adressen gleichzeitig genutzt werden.
	selector	Text	Nur MQTT: JSON Selektor
	qos	Zahl	Nur MQTT: QoS
	retain	true oder false	Nur MQTT: retain Flag
	ignore-error	true oder false	Nur MQTT: ignoriere Dekodierfehler.
switch address #text		Text	Die Gruppenadresse (z.B: 12/0/7) bei KNX-Backends, der Item-Name beim openHAB-Backend oder das Topic bei MQTT.

Die api-doc Direktive

Diese Direktive liest wichtige Informationen aus der Source-Code Dokumentation eines Widgets oder Plugins. Momentan sind das die Werte der @author und @since Angaben.

Wichtig

Wichtig ist hierbei, dass der Name des Widgets exakt dem Namen der Sourcecode-Datei ohne Dateiendung entspricht, also z.B. für structure/pure/Switch.js nimmt man .. api-doc:: Switch (Groß-/Kleinschreibung beachten). Bei Plugins muss der Ordnername des Plugins angegeben werden, also z.B. für plugins/clock/ nimmt man .. api-doc:: clock. Für Widgets von anderen Strukturen oder beliebige andere Source-Code Dateien muss man den vollen Namen der Klasse angeben wie sie in qx.Class.define angegeben ist also z.B. für qx.Class.define('cv.ui.structure.tile.Controller',... nimmt man .. api-doc:: cv.ui.structure.tile.Controller.

Beispiel für das Switch-Widget:

.. api-doc:: Switch

erzeugt folgenden Inhalt:

Autor: Christian Mayer
Verfügbar seit: 0.8.0 (2012)

Die replaces Directive

Durch diese Direktive lasst sich definieren, welche Seiten des alten Wikis durch diese Handbuch-Seite ersetzt werden. Es können mehrere Wiki-Seiten angegeben werden. Diese Direktive fügt der Dokumentation keinen Inhalt hinzu, sondern wird dazu verwendet automatisch Weiterleitungen zu erstellen.

.. replaces:: CometVisu/0.8.x/widgets/switch/de/
    CometVisu/0.8.0/switch/de
    CometVisu/Widget/switch/de
    CometVisu/switch
    CometVisu/switch_(Deutsch)