INT16/INT32 Parameters with Choice Constraints
The following hints apply to INT16, INT16_ARRAY, INT32, and INT32_ARRAY Parameters provided that they use a constraint of type CHOICE or EXTENDED_CHOICE. There are some restrictions for certain hints (checkboxes and toggle buttons are only valid for 2-choice constraints, buttons with and without prompts are only valid for single-choice and 2-choice constraints). If a widget hint is used incorrectly, the combo box will be substituted in place of the chosen widget. Display examples are provided below.
Widget Name |
Value |
Description |
WIDGET_COMBO_BOX |
7 |
Displays a dropdown list of selectable options. This is the default widget used for any choice parameter with more than 1 choice provided. |
WIDGET_CHECKBOX |
8 |
Displays a checkbox. Checkboxes only apply to parameters with exactly 2 choices. The first choice is considered false or unchecked; the second choice is considered true or checked. |
WIDGET_RADIO_HORIZONTAL |
9 |
Displays a radio button for each integer value option. The radio buttons are placed beside each other horizontally on the page. |
WIDGET_RADIO_VERTICAL |
10 |
Displays a radio button for each integer value option. The radio buttons are placed in a vertical column. |
WIDGET_BUTTON_PROMPT |
11 |
Provides a button with confirmation prompt. Whenever the button is pressed and confirmed, the parameter value is send to the device. |
WIDGET_BUTTON_NO_PROMPT |
12 |
Provides a button without confirmation prompt. Whenever the button is pressed, the parameter value is send to the device. |
WIDGET_BUTTON_TOGGLE |
13 |
Displays a toggle buttons. This hint applies only to parameters with exactly 2 choices. The first choice is shown when the button is up (not pressed); the second choice is shown when the button is down (pressed). |
WIDGET_FILE_DOWNLOAD |
18 |
Displays a file download widget. This hint requires an external object with an OID matching the value of the parameter. |
WIDGET_MENU_POPUP |
20 |
Each value in the parameter must refer to the menu ID of an OGP Menu. The choice corresponding to the parameter value has its name used as the value displayed on a button. When the button is pressed, the menu with an OID corresponding to the parameter value is displayed in a popup menu. |
WIDGET_RADIO_TOGGLE_BUTTONS |
22 |
Displays a toggle button for each integer value option. The toggle buttons are placed beside each other horizontally on the page. |
WIDGET_TREE |
31 |
Displays a tree control. Tree elements are defined by the elements of the choice constraint. The tree hierarchy is defined by “-” characters at the beginning of the choice. See detailed description below for more information. |
WIDGET_TREE_POPUP |
32 |
Displays the tree (same definition as WIDGET_TREE) in a combo box control. See detailed description below for more information. |
WIDGET_COMBO_BOX (7)
Display a dropdown list of selectable options. This is the default widget used for any choice parameter with more than 1 choice provided.
Figure 15 - WIDGET_COMBO hint
WIDGET_CHECKBOX (8)
Displays a checkbox. Checkboxes only apply to integer choice constraints with exactly 2 choices. The first choice is considered false or unchecked; the second choice is considered true or checked.
Figure 16 - WIDGET_CHECKBOX hint.
WIDGET_RADIO_HORIZONTAL (9)
Displays a radio button for each element in the choice constraint. The radio buttons are placed beside each other horizontally on the page.
Figure 17 - WIDGET_RADIO_HORIZONTAL hint
WIDGET_RADIO_VERTICAL (10)
Displays a radio button for each element in the choice constraint. The radio buttons are placed in a column vertically on the page.
Figure 18 - WIDGET_RADIO_VERTICAL hint
WIDGET_BUTTON_NO_PROMPT (12)
This hint can only be used for a parameter having a choice constraint with one or two choices. It displays a button with the name of the first choice as the button label. When the button is pressed, a parameter set request is sent to the device immediately (without user confirmation). If the parameter has only one choice, the value of that choice is sent to the device. If the parameter has two choices, the value of the second choice is sent. The device should normally reset the parameter value to the first choice when it acknowledges the set request.
Figure 19 shows a single-choice parameter named "Factory Defaults" with a hint of WIDGET_BUTTON_NO_PROMPT and a value of "Reset". There will be no confirmation dialog.
Figure 19 - WIDGET_BUTTON_NO_PROMPT hint.
WIDGET_BUTTON_PROMPT (11)
This hint can only be used for a parameter having a choice constraint with one or two choices. It is the default widget used when only one choice is available. It displays a button with the name of the first choice as the button label. When the button is pressed, a confirmation dialog is displayed before sending anything to the device. The dialog uses the format: “[Button Label] [Parameter Name]?” So a choice called “Reset” with a parameter named “Parameter Values” would display “Reset Parameter Values?” as the prompt. When the button is pressed and confirmed, a parameter set request is sent to the device. If the parameter has only one choice, the value of that choice is sent to the device. If the parameter has two choices, the value of the second choice is sent. The device should normally reset the parameter value to the first choice when it acknowledges the set request. If a two-state button is desired, see WIDGET_BUTTON_TOGGLE.
Figure 20 shows single-choice parameter named "Factory Defaults" with a hint of WIDGET_BUTTON_PROMPT and a value of "Reset".
Figure 20 - WIDGET_BUTTON_PROMPT hint
Note Two choices are necessary for using WIDGET_BUTTON_PROMPT and WIDGET_BUTTON_NO_PROMPT with array parameters.
WIDGET_BUTTON_TOGGLE (13)
Toggle buttons work exactly the same was a checkbox. The toggle button applies only to integer constraints with exactly two choices. The name of the first choice is shown when the button is up (not pressed) and the name of the second choice is shown when the button is down (pressed).
Figure 21 shows a two-choice integer parameter named "Bold Toggler" with choice 1 set to "First Value" and choice 2 set to "Second value" The figure shows the button’s display for both before and after a button toggle.
Figure 21 - WIDGET_BUTTON_TOGGLE hint
WIDGET_FILE_DOWNLOAD (18)
This hint requires that an external object with an OID matching the value of the parameter be available. For each choice in the parameter’s choice constraint, the choice value represents an external object’s OID and the value represents the filename to display. When the ‘save’ button is pressed, DashBoard requests the external object with the given OID and save the external object’s bytes to the filename/location defined by the user (default filename is defined in the choice constraint).
Figure 22 - WIDGET_FILE_DOWNLOAD hint
WIDGET_MENU_POPUP (20)
This hint requires that an OID Menu with a menu ID matching the value of the parameter be available. For each choice in the parameter’s choice constraint, the choice value represents a menu’s ID and the choice name represents the label to display on the button. When the button is pressed, DashBoard displays the menu with the given ID as a popup menu.
Figure 23 - WIDGET_MENU_POPUP hint
WIDGET_RADIO_TOGGLE_BUTTONS (22)
Displays a radio toggle button for each integer value option. The radio toggle buttons are placed beside each other horizontally on the page.
Figure 24 - WIDGET_RADIO_TOGGLE_BUTTONS hint
WIDGET_TREE (31)
Displays a tree control. Tree elements are defined by the elements of the choice constraint. The tree hierarchy is defined by “-” characters at the beginning of the choice. When an element in the tree is selected, the parameter value is set to the value of the selected choice. All other expand/collapse changes are local only to the DashBoard on which the change occurred.
“+” indicates that an element should be expanded by default.
Figure 25 - WIDGET_TREE hint
The tree pictured above is defined by the following list of choices:
1. Element 1<i:>
2. +Element 1 - 1<i-u:http://127.0.0.1/icons/small/sound2.png>
3. +Element 1 - 2<i:>
4. +-Element 1 - 2 - 1<i:>
5. +-Element 1 - 2 - 2<i:>
6. +-Element 1 - 2 - 3<i:>
7. Element 2
8. +-Element 2 - 1
9. +-Element 2 - 2
10. +-Element 2 - 2 - 1
11. +-Element 2 - 2 - 2
12. +-Element 2 - 2 - 3
13. +--Bob!
14. Element 3
15. Element 4
WIDGET_TREE_POPUP (32)
Displays the tree (same definition as WIDGET_TREE) in a combo box control. This functions the same as WIDGET_TREE, with the difference that only the currently selected item shows by default. When the user clicks on the value, a popup appears, allowing selection to be made.
Figure 26 - WIDGET_TREE_POPUP hint