Syntax für Eigenschaften

Die Syntax für Eigenschaften ist aufgrund der großen Vielfalt verschiedenster Anforderungen an eine Eigenschaft, umfangreicher als die der Aktionen.

Syntaxdiagramm für Eigenschaften

Dieses Diagramm veranschaulicht die generelle Syntax aller Eigenschaften. Eckige Klammern hinter Attributen oder Elementen geben jeweils an,

wie oft ein Element/Attribut vorkommen muss. Ist keine Mengenangabe vorhanden so muss das Element/Attribute genau einmal vorhanden sein.

<property[0..n]
name
datatype
defaultvalue >

<target[1..n]
type
element
selector
template[0..1]
regex[0..1]
regex_group_index[0..1] >

<linearmap[0..1]
inmin
inmax
outmin
outmax
precision[0..1] />

<condition[0..n]
eq[0..1]
neq[0..1]
gt[0..1]
gte[0..1]
lt[0..1]
lte[0..1]
output[0..1] />
</target>
</property>

Element: Property

Wie das action Element auch, kann das property beliebig oft vorkommen.

Hier ein Beispiel eines property Elements:

Hiermit ist eine Eigenschaft namens BoomColor definiert. Diese hat den Datentype Color, was dafür sorgt, dass im Editor ein Colorpicker für diese Eigenschaft zur Verfügung steht.

Falls kein anderer Wert festgelegt wurde, hat diese Eigenschaft den Wert #FF9523.

Alle Eigenschaften haben die gleichen 3 Pflichtattribute name, datatype und defaultvalue. Der Inhalt der Eigenschaften (oben durch … dargestellt) unterscheidet sich von Eigenschaft zu Eigenschaft.

Property Attribut: Name

Das Attribute name dient zur Identifizierung der Eigenschaft im Editor. Der Name wird unten rechts im „Eigenschaften“-Fenster angezeigt:

Property Attribut: Datatype

Das Attribut datatype gibt den Datentyp der Eigenschaft an.

Verfügbare Datentypen finden Sie im Kapitel „Konstanten“:

>> Konstanten

Property Attribut: Defaultvalue

Das Attribut defaultvalue gibt den Standardwert dieser Eigenschaft an. Mit diesem Wert wird das Steuerelement initialisiert, wenn es zum ersten Mal geladen wird.

Element: Target

Das target Element, welches mindestens einmal innerhalb einer Eigenschaft vorkommen muss, spezifiziert einen bestimmten Teil des SVG´s,

welcher mit dieser Eigenschaft verändert werden soll. Sollen mehrere Teile eines SVG´s verändert werden, so können einfach mehrere target Elemente

parallel verwendet werden.

Hier ein Beispiel eines target Elements innerhalb eines property Elements:

Dieses Beispiel beschreibt, dass bei Änderung dieser Eigenschaft (BoomColor) alle Elemente mit dem Klassennamen boombg verändert werden.

Genauer gesagt wird für alle diese Elemente das Attribut fill geändert.

Da für dieses target Element weder ein template, linearmap noch condition definiert sind, wird der Eingangswert unverändert auf das fill Attribut geschrieben.

Genaueres zu template, linearmap und condition, erfahren Sie unten stehend.

Target Attribut: Element

Das Attribut element verweist auf ein (oder mehrere) Elemente innerhalb dieses SVG´s. Dieser Verweis funktioniert mittels Klassennamen.

Im zu vorigen Beispiel muss es im SVG also ein Element mit dem Klassennamen boombg geben. Anderenfalls gibt der Editor eine Fehlermeldung aus.

Target Attribut: Type

Das Attribut type gibt an, was innerhalb des per element Attribut ausgewähltem Element verändert werden soll.

Für dieses Attribut gibt es 3 mögliche Werte:

Attribute
Style
Content

Somit lässt sich steuern, ob mit diesem target ein bestimmtes Attribut, ein bestimmter Style oder der Inhalt des Elements verändert werden soll. Für den Fall,

das ein Attribut oder ein Style verändert werden sollen, (was normalerweise der Fall sein wird) muss ein drittes Attribut (das selector Attribut) angegeben werden,

welches das konkrete Attribut oder den konkreten Style bestimmt.

Target Attribut: Selector

Das Attribut selector findet nur Verwendung, wenn als type entweder Attribute oder Style gewählt wurde. In diesen Fällen muss noch definiert werden,

welches Attribut beziehungsweise welcher Style verändert werden soll.

Target Attribut: Template

Das Attribut template kann dafür eingesetzt werden, den Wert weiter zu bearbeiten, bevor dieser auf ein Attribut, einen Style oder in den Inhalt geschrieben wird.

Im obigen Beispiel findet dieses Attribut keine Verwendung, da der Wert unverändert an das Attribut gegeben werden soll.

Hier ein Beispiel mit diesem Attribut:

<target element="boom" type="Attribute" selector="transform"

template="rotate({value} 25,60)" />

Der Ausdruck {value} ist hierbei ein Platzhalter, der mit dem eingegangen Wert ersetzt wird. So wird aus dem Wert 90 in obigem Beispiel rotate (90 25,60).

Dies entspricht einer Rotation von 90° um den Punkt 25,60.

Target Attribut: Regex

Das Attribut regex kann verwendet werden, wenn nur ein bestimmter Teil eines Attribut, Styles oder des Inhalts verändert werden soll. Dazu wird als Wert für das regex Attribut ein regulärer Ausdruck angegeben.

Hier ein Beispiel mit diesem Attribut:

<target element="target_pos" type="Attribute" selector="transform"

regex="translate\((.+) .+\)" />

Der hier angegebene reguläre Ausdruck dient dazu, nur den X-Anteil eines translate Ausdrucks zu verändern, den Y-Anteil aber unverändert zu lassen.

Der reguläre Ausdruck muss angegeben werden ohne führenden oder abschließenden Slash (/) und ohne zusätzliche Attribute.

Der reguläre Ausdruck muss so aufgebaut sein, sodass sich der zu ersetzende Teil des Strings in einer Gruppe (runde Klammern) befindet. Wichtig ist, dass es sich bei dieser Gruppe um eine Capturing Group handelt, die öffnende Klammer also nicht von einem ?: gefolgt wird.

Standardmäßig wird QuickHMI das Ergebnis der ersten (Capturing) Gruppe durch den Wert der Eigenschaft ersetzen. Andere Gruppen die sich vor dieser Gruppe befinden sollten als Non-Capturing Group definiert werden. Alternativ kann durch die Angabe des Attributes regex_group_index auch eine andere als die erste Gruppe verwendet werden, um den zu ersetzenden Teil zu kennzeichnen.

Element: Linearmap

Das Element linearmap dient zur linearen Übersetzung eines Wertes von einer Skala auf eine andere.

Zur Erklärung hier als Beispiel, die etwas komplexere Eigenschaft Level unseres Beispiel-SVG-Steuerlements RGB,

welches Sie in den Kapiteln für Beispiele in dieser Dokumentation finden:

</property>

Als Eingabewert wird hier ein Wert von 0 bis 100 erwartet. Dieser Wert soll linear auf einen Ausgabewert im Bereich von 300 bis -400 übersetzt werden.

Ein Eingabewert von 0 führt dabei zu einem Ausgabewert von 300 und ein Eingabewert von 100 führt zu einem Ausgabewert von -400.

Linearmap Attribut: Inmin

Untere Begrenzung des Eingabewertes.

Linearmap Attribut: Inmax

Obere Begrenzung des Eingabewertes.

Linearmap Attribut: Outmin

Untere Begrenzung des Ausgabewertes

Linearmap Attribut: Outmax

Obere Begrenzung des Ausgabewertes.

Linearmap Attribut: Precision

Gibt die Anzahl der Nachkommastellen an, auf die das Ergebnis der Übersetzung gerundet wird. Dieses Attribut ist optional.

Wird es weggelassen, wird das Ergebnis nicht gerundet.

Element: Condition

condition Elemente werden dazu verwendet, in Abhängigkeit des Eingangswertes einen bestimmten (in der Regel vom Eingangswert abweichenden)

Wert auf das target zu schreiben. Hier ein Beispiel eines condition Elements:

Diese Bedingung führt dazu, dass bei einem Eingabewert von True statt dem Eingabewert, der Wert rgb(246, 0, 0) auf das Target geschrieben wird.

Dies würde nun aber dazu führen, dass bei einem Eingabewert von False nichts unternommen wird, da die Bedingung eq=“True“ nicht erfüllt ist.

Für diesen Fall gibt es die Möglichkeit, beliebig viele condition Elemente aneinander zu hängen:

So wäre das Problem gelöst und alle möglichen Eingabewerte für diese Eigenschaft (Das sind nur True und False, da es sich hier um eine Eigenschaft des Types Boolean handelt)

sind abgedeckt. Folgendes Beispiel hätte allerdings das gleiche Ergebnis:

Denn ein condition Element benötigt keinen einzigen Vergleichssoperator. In dem Fall fungiert diese Bedingung als else-Fall und definiert den Wert, der geschrieben wird,

falls keine zuvor geprüfte Bedingung erfüllt war.

Eine ebenfalls möglich, aber in diesem Fall unlogische Syntax, ist folgende:

Ein condition Element ohne jegliches Attribut dient ebenfalls als else-Fall. Da hier aber kein output definiert ist, bleibt der Eingabewert unverändert.

Zu beachten ist, dass alle Bedingungen von oben nach unten abgearbeitet werden. Sobald eine Bedingung erfüllt ist, werden darauf folgende Bedingungen gar nicht erst geprüft.

Somit würde dieses Beispiel dazu führen, dass immer rgb(170, 170, 170) geschrieben wird, auch wenn der Eingabewert gleich True ist:

Condition Attribut: Vergleichsoperatoren

Für das Element condition gibt es 6 Attribute, die zur Überprüfung des Eingabewertes dienen.

eq (=)
neq (!=)
lt (<)
lte (<=)
gt (>)
gte (>=)

Da mehrere dieser Attribute gleichzeitig verwendet werden können, kann es zu Widersprüchen kommen.

Solche Widersprüche werden nicht als Fehler angezeigt, sondern führen dazu, dass diese Bedingung nie ausgeführt wird.

Wird kein Vergleichsoperator angegeben, wird diese Bedingung immer erfüllt.

Condition Attribut: Output

Definiert, welcher Wert bei Zutreffen der Bedingung geschrieben werden soll.

Wird kein output angegeben, wird der Eingabewert unverändert übernommen.