Actions and properties are defined directly in the SVG. To do this, there must be a qhmi element anywhere within the SVG.
This element can in turn contain several property or action elements that define individual properties and actions.
Here is an (incomplete) example of an SVG with one action and 2 properties:
<svg>
<qhmi>
<action ... />
<property ... >...</property>
<property ... >...</property>
</qhmi>
//Hier würde der weitere Code des SVGs folgen.
</svg>Syntax actions
Actions are defined directly in the SVG. To ensure that these are interpreted correctly by QuickHMI, the syntax explained here must be adhered to.
Syntax diagram for actions
This diagram illustrates the general syntax of all actions. Square brackets after attributes or elements indicate how often an element/attribute must occur.
If no quantity is specified, the element/attribute must be present exactly once.
<action[0..n]
name
elements
triggers >Element: Action
A action element can be present any number of times in the qhmi element.
Here is an example of an action element:
<action name="OnPaletteClicked" elements="palette" triggers="click" />This example action is listed in the editor with the name OnPaletteClicked and is triggered when you click (click) on an element with the class palette within the SVG.
All actions have the same structure and differ only in the values of the three attributes name, triggers and elements.
Action attribute: Name
The name attribute determines the name under which this action is displayed in the editor. Using the action above as an example, it would look like this in the editor:
Action attribute: Elements
Specifies one or more elements within this SVG that should trigger this action. The assignment is made via class names. In this example, there must be (at least) one element with the class palette within the SVG.
Multiple class names in the elements attribute must be separated by spaces.
Action attribute: Triggers
Specifies one or more events (e.g. “click” or “mousedown”) that should trigger this action. JavaScript events can be specified here, separated by spaces.
You can find a list of JavaScript events on the following external website:
* https://www.w3schools.com/jsref/dom_obj_event.asp
*| We have no influence on the content of external websites.
Syntax for properties
The syntax for properties is more extensive than that for actions due to the wide variety of different requirements for a property.
Syntax diagram for properties
This diagram illustrates the general syntax of all properties. Square brackets after attributes or elements indicate how often an element/attribute must occur.
If no quantity is specified, the element/attribute must be present exactly once.
<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
Like the action element, the property can occur as often as you like.
Here is an example of an property element:
<property name="BoomColor" datatype="Color" defaultvalue="#FF9523" >…</property>This defines a property called BoomColor. This has the data type Color, which ensures that a color picker is available for this property in the editor.
If no other value has been specified, this property has the value #FF9523.
All properties have the same 3 mandatory attributes name, datatype and defaultvalue. The content of the properties (represented above by …) differs from property to property.
Property attribute: Datatype
The attribute datatype specifies the data type of the property.
Property attribute: Defaultvalue
The attribute defaultvalue specifies the default value of this property. The control is initialized with this value when it is loaded for the first time.
Element: Target
The target element, which must occur at least once within a property, specifies a certain part of the SVG that is to be changed with this property.
If several parts of an SVG are to be changed, several target elements can simply be used in parallel.
Here is an example of a target element within a property element:
<property name="BoomColor" datatype="Color" defaultvalue="#FF9523" >
<target element="boombg" type="Attribute" selector="fill" />
</property>This example describes that when this property (BoomColor ) is changed, all elements with the class name boombg are changed.
More precisely, the attribute fill is changed for all these elements.
As neither template, linearmap nor condition are defined for this target element, the input value is written unchanged to the fill attribute.
You can find out more about template, linearmap and condition below.
Target attribute: Element
The attribute element refers to one (or more) elements within this SVG. This reference works by means of class names.
In the previous example, there must therefore be an element with the class name boombg in the SVG. Otherwise, the editor will display an error message.
Target attribute: Type
The attribute type specifies what is to be changed within the element selected via the element attribute.
There are 3 possible values for this attribute:
- Attributes
- Style
- Content
This allows you to control whether a specific attribute, a specific style or the content of the element is to be changed with this target.
In the event that an attribute or a style is to be changed, a third attribute (the selector attribute) must be specified, which determines the specific attribute or the specific style.
Target attribute: Selector
The attribute selector is only used if either Attribute or Style has been selected as type . In these cases, you still need to define which attribute or style is to be changed.
Target attribute: Template
The attribute template can be used to further edit the value before it is written to an attribute, a style or in the content.
This attribute is not used in the above example, as the value should be passed to the attribute unchanged.
Here is an example with this attribute:
<target element="boom" type="Attribute" selector="transform"
template="rotate({value} 25,60)" /> The expression {value} is a placeholder that is replaced with the entered value. So the value 90 in the example above becomes rotate (90 25,60).
This corresponds to a rotation of 90° around the point 25.60.
Target attribute: Regex
The regex attribute can be used if only a specific part of an attribute, style or content is to be changed. For this purpose, a regular expression is specified as the value for the regex attribute.
Here is an example with this attribute:
<target element="target_pos" type="Attribute" selector="transform"
regex="translate\((.+) .+\)" />The regular expression specified here is used to change only the X part of an translate expression, but leave the Y part unchanged.
<g class="target_pos" transform="translate(0 100)" />The regular expression must be specified without a leading or trailing slash (/) and without additional attributes.
The regular expression must be structured in such a way that the part of the string to be replaced is in a group (round brackets). It is important that this group is a capturing group, i.e. that the opening bracket is not followed by a ?:.
By default, QuickHMI will replace the result of the first (capturing) group with the value of the property. Other groups before this group should be defined as non-capturing groups. Alternatively, by specifying the attribute regex_group_index , a group other than the first group can be used to identify the part to be replaced.
Element: Linear map
The element linearmap is used for the linear translation of a value from one scale to another.
To explain this, here is an example of the somewhat more complex property Level of our sample SVG control element Rack feeder, which is described further in the chapter Properties and actions of the control elements in this documentation:
<property
name="Level"
datatype="Int16"
defaultvalue="0">
<target
type="Attribute"
element="verticalsled"
selector="transform"
template="matrix(1, 0, 0, 1, 0, {value})">
<linearmap
inmin="0"
inmax="100"
outmin="300"
outmax="-400"
precision="0" />
</target>
</property>A value from 0 to 100 is expected as the input value. This value is to be translated linearly to an output value in the range from 300 to -400.
An input value of 0 leads to an output value of 300 and an input value of 100 leads to an output value of -400.
A linearmap is carried out before evaluating any condition elements that may be present.
Linearmap attribute: Inmin
Lower limit of the input value.
Linearmap attribute: Inmax
Upper limit of the input value.
Linearmap attribute: Outmin
Lower limit of the output value.
Linearmap attribute: Outmax
Upper limit of the output value.
Linearmap attribute: Precision
Specifies the number of decimal places to which the result of the translation is rounded. This attribute is optional.
If it is omitted, the result is not rounded.
Element: Condition
condition Elements are used to write a specific value (usually different from the input value) to the target depending on the input value.
Here is an example of an condition element:
<target type="Style" element="palettestatus" selector="stroke">
<condition eq="True" output="rgb(246, 0, 0)" />
</target>This condition means that if the input value is True instead of the input value, the value rgb(246, 0, 0) is written to the target.
However, this would result in nothing being done if the input value is False, as the condition eq=“True“ is not fulfilled.
In this case, it is possible to attach any number of condition elements to one another:
<target type="Style" element="palettestatus" selector="stroke">
<condition eq="True" output="rgb(246, 0, 0)" />
<condition eq="False" output="rgb(170, 170, 170)" />
</target>This would solve the problem and all possible input values for this property (these are only True and False, as this is a property of the type Boolean type)
are covered. However, the following example would have the same result:
<target type="Style" element="palettestatus" selector="stroke">
<condition eq="True" output="rgb(246, 0, 0)" />
<condition output="rgb(170, 170, 170)" />
</target>This is because an condition element does not require a single comparison operator. In this case, this condition acts as an else case and defines the value that is written if no previously checked condition was fulfilled.
The following syntax is also possible, but illogical in this case:
<target type="Style" element="palettestatus" selector="stroke">
<condition eq="True" output="rgb(246, 0, 0)" />
<condition />
</target>An condition element without any attribute also serves as an else case. However, as no output is defined here, the input value remains unchanged.
It should be noted that all conditions are processed from top to bottom. As soon as a condition is fulfilled, the following conditions are not even checked.
This example would therefore result in rgb(170, 170, 170) always being written, even if the input value is True:
<target type="Style" element="palettestatus" selector="stroke">
<condition output="rgb(170, 170, 170)" />
<condition eq="True" output="rgb(246, 0, 0)" />
</target>All
conditionelements are only checked after a possiblelinearmaphas been applied.
Condition attribute: Comparison operators
There are 6 attributes for the element condition, which are used to check the input value:
- eq (=)
- neq (!=)
- lt (
- lte (<=)
- gt (>)#
- gte (>=)
As several of these attributes can be used at the same time, contradictions may arise.
Such contradictions are not displayed as errors, but result in this condition never being executed.
If no comparison operator is specified, this condition is always fulfilled.
Condition attribute: Output
Defines which value is to be written if the condition is met.
If no output is specified, the input value is accepted unchanged.
