added multi-buttons!

docs/Button/Button Representations/Basic.md

@@ -83,6 +83,9 @@ For example, for an OnOff activation type there may be two icons for On and Off
 
 No attribute.
 
+> [!NOTE] Multi
+> Cockpitdecks offers representations like multi-icons, multi-texts, and even multi-buttons always on the same pattern. The multi- keyword means that there are several representations of the same type available in the button definition. The *value* of the button determine which one if chosen for representation. If the value of the button does not point at a valid index in the list, the representation is ignored.
+
 # MultiTexts
 
 `multi-texts`
@@ -127,6 +130,10 @@ The selection of the text block must be performed by a **formula** and not a dat
 
 When a formula is present in the attributes of a button, it is always favored over a list of datarefs, even if the list contains only one dataref. (If there a button uses multiple datarefs and there is no formula, the value that is returned for that button is a diectionary of all dataref values.)
 
+# Multi-Buttons
+
+See [[Multi-Buttons and Mosaic]].
+
 # LED
 
 `led: led

docs/Button/Button Representations/Mosaic.md → docs/Button/Button Representations/Multi-Buttons and Mosaic.md

@@ -1,3 +1,11 @@
+Multi-Buttons and Mosaic allow simultaneous representation of several buttons.
+
+Multi-buttons selects one button to represent from a list of buttons.
+
+Mosaic represent them all at once, simultaneously.
+
+# Mosaic
+
 A Mosaic is a trick used to split a large button into smaller ones.
 
 A Mosaic can, in some regards, be considered as a special case of a Page. Yes, a small page with its own set of individual buttons.
@@ -113,3 +121,9 @@ The representation must be `mosaic`. THe representation collects the representat
 ## Representation
 
 (picture, later)
+
+# Multi-Buttons
+
+The multi-button representation defines a list of buttons.
+
+The value of the main hosting button determine which button gets chosen from the list (index value).

docs/Button/Set Dataref.md

@@ -28,6 +28,6 @@ The indent of the above button is to display a counter of how many times the but
 1. The button is pressed, the activation is triggered.
 2. The activation executes the push instruction AND INCREMENT the activation counter.
 3. It is only after the counter that has been incremented that the formula is evaluated and the new value of the button is computed
-4. The new value of the button is computed and saved in the dataref pointed by `set-dataref`.
+4. The new value of the button just computed is optionally saved in the dataref pointed by `set-dataref`.
 
-So, in case the value of button is computed from one or more values that are very precisely modified by the activation of the button, the modification of the values is registered first, and the final value of the button computed afterwards, just before it is optionnaly written to the dataref pointed by the `set-dataref` attribute.
+So, in case the value of button is computed from one or more values that are very precisely modified by the activation of the button, the modification of the values is registered first, and the final value of the button computed afterwards, just before it is optionally written to the dataref pointed by the `set-dataref` attribute.

docs/Extending/Internals/Hardware Representation.md

@@ -0,0 +1,15 @@
+ Hardware Representations only exist for web decks.
+
+ When a web deck tries to reproduce on screen hardware elements only available on physical decks, it uses *hardware representation*.
+
+ Let us take a very simple hardware representation: A translucent button with a colored led. The button has sign on it (letter, number, icon…)
+![[hardware-representation.png]]
+ For the physical deck, the deck device driver will handle the rendering of the feedback on that deck through a dedicated representation and its accompanying driver software.
+
+ Cockpitdecks uses a hardware representation to draw the same button on a web deck. A hardware representation is nothing more than an image used to represent a button on a web deck.
+
+ Very much like the physical representation, Cockpitdecks uses dedicated software to create the image, but once created, the image of the hardware button is sent to the web deck for drawing like any other image, supplying the image of course, but also its position and size.
+
+ Since a hardware representation is an image, all hardware representations are in fact particular icons image and treated as such.
+
+ In the case of our translucent button, all we need is a image of that button when it is not lit. When lit with a given color and/or intensity, the hardware representation software will overlay the button sign to give the illusion that it is lit as requested. The resulting image is sent to the web deck to give the illusion of the lit button.