Sitezmap: new Buttongrid element (#2176)

* Sitezmap: new Buttongrid element Signed-off-by: Laurent Garnier <lg.hc@free.fr> * Review comments addressed Signed-off-by: Laurent Garnier <lg.hc@free.fr> --------- Signed-off-by: Laurent Garnier <lg.hc@free.fr>
openhab · Dec 16, 2023 · b656ddc · b656ddc
1 parent 0cd203c
commit b656ddc
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 0 deletions.
diff --git a/ui/images/sitemap_demo_buttongrid.png b/ui/images/sitemap_demo_buttongrid.png
diff --git a/ui/sitemaps.md b/ui/sitemaps.md
@@ -144,6 +144,7 @@ The following element types may be used in a Sitemap definition file.
 
 | Element                                  | Description                                                                               |
 | ---------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [Buttongrid](#element-type-buttongrid)   | Renders a grid of stateless buttons used to send commands to a given Item.                |
 | [Chart](#element-type-chart)             | Adds a time-series chart object for [persisted](persistence.html) data.                   |
 | [Colorpicker](#element-type-colorpicker) | Allows the user to choose a color from a color wheel.                                     |
 | [Default](#element-type-default)         | Renders an Item in the default UI representation specified by the type of the given Item. |
@@ -301,6 +302,43 @@ Switch item=LR_TV_Channel label="TV Channel" mappings=[0="DasErste", 1="BBC One"
 ![Presentation of the On/Off Switch element in BasicUI](images/sitemap_demo_switch1.png)
 ![Presentation of the multi-state Switch element in BasicUI](images/sitemap_demo_switch2.png)
 
+### Element Type 'Buttongrid'
+
+```java
+Buttongrid item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] [buttons="<Button definition>"]
+```
+
+A Buttongrid represents a grid of buttons and enables commands to be sent to an Item.
+When a button is pressed, the associated command is sent to the linked Item.
+Buttons never appear as selected, they do not display the current state of the linked Item.
+
+This is a typical element for simulating a remote control, for example.
+
+- `label` if set, a header row will be displayed containing this label and the icon.
+- `buttons` defines the position of each button within the grid and the command associated with each button; provided as an array.
+
+Buttons syntax:
+
+```java
+buttons=[row_1:column_1:command_1="description_1", row_2:column_2:command_2="description_2"=<iconname>, ...]
+```
+
+The buttons can be defined in any order, their position in the grid is defined by a row index and a column index.
+The top left position is row index 1 and column index 1.
+The grid must not exceed 12 columns so the maximum allowed column index is 12 columns.
+It is not mandatory to define a button in all grid cells.
+The user interfaces will automatically determine the grid size so that all buttons are presented.
+
+The content of each button can be text but also an icon; the icon will be used by default if provided.
+
+**Examples:**
+
+```java
+Buttongrid label="Remote Control" staticIcon=screen item=RemoteControl buttons=[1:1:POWER="Power"=switch-off , 1:2:MENU="Menu" , 1:3:EXIT="Exit" , 2:2:UP="Up"=f7:arrowtriangle_up , 4:2:DOWN="Down"=f7:arrowtriangle_down , 3:1:LEFT="Left"=f7:arrowtriangle_left , 3:3:RIGHT="Right"=f7:arrowtriangle_right , 3:2:OK="Ok" , 2:4:VOL_PLUS="Volume +" , 4:4:VOL_MINUS="Volume -" , 3:4:MUTE="Mute"=soundvolume_mute]
+```
+
+![Presentation of the Buttongrid element in BasicUI](images/sitemap_demo_buttongrid.png)
+
 ### Element Type 'Selection'
 
 ```java