[sitemap] Press & release feature for buttons in a switch element (op…

…enhab#2293) Related to openhab/openhab-core#4183 and openhab/openhab-core#3822 Signed-off-by: Laurent Garnier <[email protected]>
stefan-hoehn · May 12, 2024 · b01b68f · b01b68f
1 parent 7ec3f89
commit b01b68f
Showing 1 changed file with 7 additions and 2 deletions.
diff --git a/ui/sitemaps.md b/ui/sitemaps.md
@@ -295,7 +295,7 @@ A Switch will present a discrete state Item and allow changing of its value.
 Note that Switch elements can be rendered differently on the user interface, based on the Item type and the `mappings` parameter.
 
 - `mappings` comes as an array of value-to-string translations, [documented further down](#mappings).
-  Without the mappings parameter, user interfaces will present an On/Off Switch, if mappings are given, several buttons with label or icon will be rendered.
+  Without the mappings parameter, user interfaces will present an On/Off Switch, if mappings are given, several buttons with label or icon will be rendered and each button can behave either as a click button or as a press and release button.
 
 **Examples:**
 
@@ -596,7 +596,7 @@ Mappings is an optional parameter for the [Switch](#element-type-switch) and [Se
 Mapping syntax:
 
 ```java
-mappings=[value_1="description_1", value_2="description_2"=<iconname>, ...]
+mappings=[value_1="description_1", value_2="description_2"=<iconname>, value_press:value_release="description_3", ...]
 ```
 
 Examples:
@@ -609,6 +609,8 @@ mappings=[OFF="All heaters off"]
 mappings=[15="Gone", 19="Chilly", 21="Cozy"]
 
 mappings=[ON="Mic On"=material:mic, OFF="Mic Off"=material:mic_off]
+
+mappings=[ON:OFF="On"]
 ```
 
 As you can see, different Item data types are accepted as mappings values.
@@ -627,6 +629,9 @@ This limits the possible input values, which is yet another often occurring use
 In the fifth example above, user interfaces will display buttons using the provided icon rather than the provided description.
 Icons are usable in Switch element but ignored in Selection element.
 
+In the sixth example above, as there are 2 commands provided separated by a semicolon, user interface will consider a press and release behavior, the first command (ON in the example) is sent to the item when the button is pressed and the second command (OFF in the example) is sent when the button is finally released.
+This behavior is only applicable for a `Switch` element.
+
 ## Dynamic Sitemaps
 
 All Sitemap elements can be configured to be hidden, color highlighted or to have a [dynamic icon]({{base}}/configuration/items.html#dynamic-icons), depending on certain Item states.