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.

Button

Autor: Tobias Bräutigam
Verfügbar seit: 2022

Beschreibung

Der Button unterstützt unterschiedliche Betriebsmodi, die im folgenden beschrieben werden.

Schalter

Ein Schalter-Button erlaubt das Senden und Darstellen eines Zustands. Das einfachste Beispiel hierfür ist ein An/Aus-Schalter. Der Button zeigt den aktuellen Zustand an und wechselt beim Klicken zwischen den beiden möglichen Zuständen.

...
<cv-meta>
    <cv-mapping name="light">
        <entry value="0">ri-lightbulb-line</entry>
        <entry value="1">ri-lightbulb-fill</entry>
    </cv-mapping>
    <cv-styling name="button">
        <entry value="0">inactive</entry>
        <entry range-min="1">active</entry>
    </cv-styling>
</cv-meta>
...
<cv-button mapping="light" styling="button">
    <cv-address transform="DPT:1.001" mode="readwrite">1/4/2</cv-address>
    <cv-icon class="value">ri-question-mark</cv-icon>
</cv-button>

Um die Darstellung des aktuellen Zustands zu verbessern wird in dem Beispiel ein „mapping“ verwendet, welches bewirkt das je nach Zustand ein anderes Icon benutzt wird. Zusätzlich wird über ein „styling“ noch die Farbe des Icons und der Umrandung des Buttons je nach Zustand unterschiedlich gesetzt.

Trigger

Ein Trigger-Button sendet dann beim Klicken immer einen festen Wert an das Backend. Hier ist der gesendete Wert also nicht wie beim Schalter abhängig vom aktuellen Zustand, sondern es wird immer ein und der selbe Wert gesendet. Eingestellt wird dieser Modus indem der zu sendende feste Wert in dem <cv-address>-Element angeben wird:

<cv-address transform="DPT:1.001" mode="readwrite" value="1">1/4/2</cv-address>

Taster

Ein Taster-Button sendet einen Wert beim Drücken des Buttons und beim Loslassen des Buttons einen anderen. Im Trigger- und Schalter-Modus wird nur ein Wert beim Loslassen des Buttons gesendet (einfacher Klick). Auch dieser Modus wird über das <cv-address>-Element aktiviert. Genauer gesagt benötigt man hier zwei Adressen:

<cv-address transform="DPT:1.001" mode="readwrite" value="1" on="down">1/4/2</cv-address>
<cv-address transform="DPT:1.001" mode="readwrite" value="0" on="up">1/4/2</cv-address>

Hier wird beim Drücken (on="down") der Wert 1 an 1/4/2 und beim Loslassen (on="up") der Wert 0 gesendet.

Weitere Eigenschaften

Runder Button

Als zusätzliche Option kann der Button als Kreis dargestellt werden, dazu muss lediglich dem <cv-button>-Element ein class="round-button" hinzugefügt werden.

<cv-button class="round-button" mapping="light" styling="button">

Fortschrittsanzeige

Der Rand des Buttons kann auch genutzt werden um einen Prozentwert darzustellen. So kann man z.B. den Fortschritt eines gerade spielenden Liedes, eine Lautstärke oder den Helligkeitswert eines Dimmers darstellen.

Hinweis

Damit der Rand des Buttons und der Fortschrittsbalken übereinander liegen sollte hier immer der runde Button verwendet werden.

...
<cv-meta>
    <cv-mapping name="light">
        <entry value="0">ri-lightbulb-line</entry>
        <entry value="1">ri-lightbulb-fill</entry>
    </cv-mapping>
    <cv-styling name="button">
        <entry value="0">inactive</entry>
        <entry range-min="1">active</entry>
    </cv-styling>
</cv-meta>
...
<cv-button class="round-button" mapping="light" styling="button">
    <cv-address transform="DPT:1.001" mode="readwrite">1/4/2</cv-address>
    <cv-address transform="DPT:5.001" mode="read" target="progress">1/4/1</cv-address>
    <cv-icon class="value">ri-question-mark</cv-icon>
</cv-button>

Zusätzliche Beschriftung

Optional kann der Button über ein name-Attribut eine zusätzliche Beschriftung erhalten.

<cv-button class="round-button" mapping="light" styling="button" name="Licht">

Erlaubte Attribute

Element	Attribut
	Name	Inhalt	Beschreibung
cv-button	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
	progress-mapping	Text	Ordnet den Werten vom Bus andere Werte, Texte oder Symbole zur Anzeige zu. Siehe auch Mapping
	format	Text	Formatierung des Wertes (printf-Syntax).
	size	small, normal oder large	Legt die Größe des Buttons fest.
	name	Text	Zusätzliche Beschriftung für den Button.
	whole-tile	true oder false	Erweitert den klickbaren Bereich auf die gesamte Kachel.
	doc-link	Text	Link in die CometVisu-Dokumentation (wird in der Demo-Config benutzt).
	on-value	Text	Wert für den An-Zustand. Default ist „1“.
	off-value	Text	Wert für den Aus-Zustand. Default ist „0“.
	visible-on	mobile oder desktop	Steuert die Sichtbarkeit dieses Elements anhand der Bildschirmgröße.
	class	Text	Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
	style	Text	Individuelle CSS style Regeln für dieses Widget.

Erlaubte Kind-Elemente und deren Attribute

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
cv-button cv-address	transform	Text	Legt den Datentyp im Backend fest, z.B. DPT:1.001 für den KNX Datenpunkttyp 1.001.
	mode	disable, read, write oder readwrite	Legt fest, ob auf dieser Adresse nur gelesen `read`, geschrieben `write`, beides `readwrite` oder nichts davon `disable` werden soll
	value	Text	Fixer Wert welcher an diese Adresse gesendet wird.
	on	click, down oder up	Event bei dem ein Wert and diese Adresse geschickt wird (nur in Verbindung mit `value` und mode=``read`` oder `readwrite`).
	target	Text	Ziel innerhalb der Eltern-Widgets für das die Werte dieser Adresse benutzt werden sollen. Die möglichen Werte hängen vom Eltern-Widget ab.
	format-pos	Zahl	Position für Format-String wenn mehrere Adressen gleichzeitig genutzt werden.
	qos	Zahl	Nur MQTT: QoS
	retain	true oder false	Nur MQTT: retain Flag
	selector	Text	Nur MQTT: JSON Selektor
	backend	Text	Optionaler Name des Backends zu dem diese Adresse gehört.
	mapping	Text	Ordnet den Werten vom Bus andere Werte, Texte oder Symbole zur Anzeige zu. Siehe auch Mapping
	format	Text	Formatierung des Wertes (printf-Syntax).
	delay	positiveInteger	Optionales delay in Millisekunden, um welches das Schreiben an diese Adresse verzögert wird.
	send-mode	on-change oder always	Normalerweise bekommen Elemente, die diese Adresse benutzen nur eine Update-Benachrichtigung, wenn sich der Wert tatsächlich geändert hat (`on-change`). Mit `always` wird diese Überprüfung umgangen und die Update-Benachrichtigung jedes Mal geschickt, wenn ein neuer Wert vom Backend empfangen wurde.
cv-button cv-address #text		Text	Die Gruppenadresse (z.B: 12/0/7) bei KNX-Backends, der Item-Name beim openHAB-Backend oder das Topic bei MQTT.

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
cv-button cv-icon	size	small, large, x-large, xx-large oder xxx-large	Legt die Größe des Icons fest.
	color	Text	Farbe des Icons.
	visible-on	mobile oder desktop	Steuert die Sichtbarkeit dieses Elements anhand der Bildschirmgröße.
	class	Text	Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
	style	Text	Individuelle CSS style Regeln für dieses Widget.
cv-button cv-icon #text		Text

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
cv-button p	visible-on	mobile oder desktop	Steuert die Sichtbarkeit dieses Elements anhand der Bildschirmgröße.
	class	Text	Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
	style	Text	Individuelle CSS style Regeln für dieses Widget.
cv-button p 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.
cv-button p label #text		Text	Text um bei dem Widget eine Beschreibung darzustellen.
cv-button p #text		Text

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
cv-button label	tr	true oder false	Legt fest, dass der Text-Inhalt dieses Elements übersetzt werden soll.
	value-size	small, medium, normal oder large	Legt die Schriftgröße fest.
	visible-on	mobile oder desktop	Steuert die Sichtbarkeit dieses Elements anhand der Bildschirmgröße.
	class	Text	Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
	style	Text	Individuelle CSS style Regeln für dieses Widget.
cv-button label #text		Text