The LatchingButtonElement works much like the ParameterButtonElement described later in this document, but is specialized to show and control an enumeration parameter which knows exactly two states (e.g. on/off or true/false).
When the operator changes the state of the button by clicking it once, the latching button sends the 'other' parameter value to the device. On the other hand, if some other instance in the system changes the parameter state, the latching button recognizes this and changes the up/down state of the button accordingly.
Like the parameter button, the latching button may be labeled with text or an image. To reflect the actual state, the latching button always is configred with two text string or two image names which are shown according to the actual parameter value.
Data Model (extends ScreenElement)
| Key | Type | Value |
|---|---|---|
| type | String | Always "LatchingButtonElement". |
| xpos | Number | see ScreenElement |
| ypos | Number | see ScreenElement |
| width | Number | see ScreenElement |
| height | Number | see ScreenElement |
| id | String | The message ID this element listens for |
| privilege | Number | The privilege level required to change the button state / parameter value |
| labelUp | String | The label shown on the button when not pressed |
| labelDown | String | The label shown on the button when pressed |
| iconUp | String | The icon shown on the button when not pressed |
| iconDown | String | The icon shown on the button when pressed |
| enableId | String | The enable ID (may be empty) |
| enableValue | String | The value which must be matched to enable the field |
| font | String | The font to be used for the button label |
| color | String | The color used for the label |
| mustQuery | Boolean | Show a query popup before changing the value |
| queryText | String | the text to show in the query |
| valueUp | String | The parameter value to send when the button is going up |
| valueDown | String | The parameter value to send when the button is going down |
| variableBackgroundColor | Boolean | true = use a variable background color |
| colorId | String | The message ID to listen for the background color |
| colors | Array | of ColorDefinition objects. Defines how to translate values of the colorId parameter to color values. |
The LatchingButtonElement never uses a button label and an icon at the same time. Either iconUp / iconDown or labelUp / labelDown contain empty strings.
The valueUp and valueDown values are not only sent when the button is pressed or released. They also are used to set the button state when a parameter value is received though id: If the value matches valueDown the button goes to 'pressed' state, in all other cases the button gets released. Labels or icons change an this moment according to the new state.