Hints for String Parameters
The following widget hints may be used for String parameters (in addition to the separators and layout hints defined above). The last two hints apply only to a String parameter using the reserved objectID 0xFF01.
Widget Name |
Value |
Description |
WIDGET_TEXT_ENTRY |
3 |
Displays a normal text entry field. This is the default for editable String parameters. |
WIDGET_PASSWORD |
4 |
Displays an entry field for passwords (text entered in this field is obscured). |
WIDGET_COMBO_ENTRY |
11 |
Displays an entry field together with a dropdown list of selectable items. This is applicable only with the STRING_CHOICE constraint. |
WIDGET_COLORED_DOT |
12 |
Displays a colored icon. The icon color is specified using a tag in the text string. |
WIDGET_RICH_LABEL |
13 |
Displays a read-only multi-line text field with HTML formatting. |
WIDGET_MULTILINE_TEXT_ENTRY |
14 |
Displays a multi-line text editor. |
WIDGET_NAME_OVERRIDE_APPEND |
0 |
Special hint only for objectID 0xFF01 – causes this string to be appended to the displayed product name |
WIDGET_NAME_OVERRIDE_REPLACE |
1 |
Special hint only for objectID 0xFF01 – causes this string to replace the product name to be displayed |
WIDGET_TEXT_ENTRY (3)
This is a text entry field used to enter String values. This is the default widget used with editable String parameters. It is very important to correctly set the length of the String with this widget as the length affects the width of the text field. In DashBoard the value is sent to the device when the user hits ‘Enter’ or changes focus to a different control on the screen.
Figure 46 - WIDGET_TEXT_ENTRY hint
WIDGET_PASSWORD (4)
This is a text entry field used to enter passwords. When the device receives a set message for a parameter using this hint, a device could send an empty string back to the device to clear the password field. Text in the password field is sent when it has changed from the value reported from the device and the user hits “Enter” or moves focus to another control.
Figure 47 - WIDGET_PASSWORD hint
WIDGET_COMBO_ENTRY (11)
This displays a text entry field along with a dropdown list. This option is available only for String parameters having a STRING_CHOICE constraint. The user may select an option from the dropdown list, or can type any value in the entry field. The text is sent to the device when a dropdown item is selected, when the user presses “Enter” or moves the focus after typing a value.
Figure 48 - WIDGET_COMBO_ENTRY hint, selecting from the dropdown list
WIDGET_COLORED_DOT (12)
This displays a colored icon. This should not be confused with Alarm parameters which have a similar appearance. The tag specifies the 24-bit RGB color index of the icon in hex, in the format <#RRGGBB>. If the string does not contain a valid color tag, the icon is drawn but not filled (i.e. background shows through).
Figure 49 - WIDGET_ICON_DISPLAY hint, and value “<#3F3FFF>”
WIDGET_RICH_LABEL (13)
This displays a read-only multi-line text field, and formats the text according to the HTML formatting tags embedded in the text. Total string length including tags is limited to 250 bytes. The display uses html support within the java display object, so the exact appearance of the label may vary depending on operating system and java version.
Figure 50 - WIDGET_RICH_LABEL hint
WIDGET_MULTILINE_TEXT_ENTRY (14)
This displays a multi-line text entry field. The amount of data a user can input into the field is limited by the maximum length specified by the parameter. The size of the field is the same regardless of the maximum number of bytes the user is allowed to enter. If the parameter’s value spans more lines than the number of rows represented by the text field, a vertical scrollbar is shown to allow the user to scroll. Text will be wrapped to avoid horizontal scrollbars.
Figure 51 - WIDGET_MULTILINE_TEXT_ENTRY hint
WIDGET_NAME_OVERRIDE_APPEND (0)
This is a special hint ONLY FOR OID 255.1 (0xFF01). This causes the value of the String parameter with OID 255.1 to be appended to the end of the device name in DashBoard.
Figure 52 shows the result of setting parameter 255.1 to " (XPF)" with a WIDGET_NAME_OVERRIDE_APPEND hint.
Figure 52 - WIDGET_NAME_OVERRIDE_APPEND hint
WIDGET_NAME_OVERRIDE_REPLACE (1)
This is a special hint ONLY FOR OID 255.1 (0xFF01). This causes the value of the String parameter with OID 255.1 to be displayed as the device name instead of the product name (OID 0x0105) in DashBoard. This is the only supported method for changing a product name dynamically. Devices should never modify their base product name (OID 0x0105); DashBoard, DataSafe, and User Rights all depend on the base product name remaining fixed. Change of the product name is assumed to mean that the user has physically removed a card, and has replaced it with a different type of card.
Figure 53 shows the result of setting parameter 255.1 to "My Device Name" with a WIDGET_NAME_OVERRIDE_REPLACE hint.
Figure 53 - WIDGET_NAME_OVERRIDE_REPLACE hint