List Box object

The List Box screen object displays a list of messages or menu items for the user to select from. When the user selects a message, its corresponding numerical value is written to a project tag.

If the list of messages is too long to fit within the viewable area of the List Box object, the object provides scroll bars.

The user can browse the list and make a selection by doing one of the following, depending on how you design your project interface:
  • Use mouse or touchscreen input to click/tap the list’s scroll bar and then select a message;
  • Press the Up, Down, Esc, Tab and/or Enter keys on the keyboard or keypad; or
  • Use on-screen controls (e.g., Button objects, linked symbols) that have been configured with the PostKey function to post the equivalent key codes.

Generally, when you run a project, the active List Box object displays a list of messages. On a screen containing only one List Box object and no text input boxes, the List Box object will be active automatically. On a screen containing multiple List Box objects and text input boxes, you can use a cursor (pointing device) or the Tab key to select and activate a List Box object.

To add a List Box object to a screen:
  1. On the Graphics tab of the ribbon, in the Active Objects group, click List Box.
  2. Draw the List Box object in the screen, and then drag object’s handles to adjust its size.

    The height of the object and the font size determine how many messages are visible. The width of the object determines how much of the message length is visible.

    After you draw the object, you can adjust the size and font characteristics to allow more messages to display in the given space.

  3. Double-click on the object to open the Object Properties dialog.
Figure 1. Object Properties: List Box
Web Studio Help dialog objectproperties listbox List Box object

You can use this dialog to specify the following parameters:
  • Value drop-down list (located below the Replace button): Click to select one of the following the tag values used to index the message list.
    • Boolean
    • Integer (default)
    • LSB (Least Significant Bit)
      Note: For more information, see the discussion about the State field on the Messages Configuration dialog.
  • Messages button: Click to open the Messages Configuration dialog (see below).
  • User Enable text box: Type a tag, expression, or a (nonzero) number to select a message in the runtime project. The default is 1 (true or enabled).
  • Control Enable text box: Type a tag, expression, or a (nonzero) number to select a message in the runtime project — depending on the current value of the Read/Search Tag. The default is 1 (true or enabled).

    IWS bases this parameter on the Value field (in the Messages Configuration dialog) that you associate with the selected message. Enabling this field allows tag changes triggered by the process to affect which messages you can select.

  • Read/Search Tag text box: Type an integer or a Boolean tag to point to a selected message based on the message Value field (in the Messages Configuration dialog). You can use the Control Enable and User Enable fields to control whether the operator or a process can alter this tag.
  • Write Tag text box (optional): Type a string tag to receive the Message value of the last-selected message. When you close and reopen the screen containing a List Box object, IWS uses this tag value to determine the last message selected in the list box.
  • E-Sign checkbox: When this option is checked, the user will be prompted to enter the Electronic Signature when using this object.
  • Row checkbox: Click (check) to include set up and set down arrows in the List Box object scroll bar.
  • Page checkbox: Click (check) to include page up and page down arrows in the List Box object scroll bar.
  • Start/End checkbox: Click (check) to include home and end arrows in the List Box object scroll bar.
  • List wrap checkbox: Click (check) to continue displaying and scrolling the message list (starting at the opposite end) after you scroll to the beginning or end of the list.
  • Require enter for selection checkbox: Clicking (checking) this box requires the user to press Enter (or post the equivalent key code) to make a selection. If this option is not checked, then a selection is made whenever focus changes to another screen object (i.e., the user tabs out of the list or clicks/taps on another object).
  • Color boxes: Click a color box to open the Color dialog or the 16-color Color Selection dialog. Either dialog allows you to specify or change colors for the List Box object. Click a color to select it and then click OK to close the dialog.
    • Highlight Color box: Specify a color for highlighting messages (default is blue).
    • Text Color box: Specify a color for highlighting message text (default is black).
    • Win Color box: Specify a color for the list box background (default is white).
    • Border Color box: Specify a color for the list box border (default is black).

Messages Configuration Dialog

Figure 2. Message Configuration dialog
Web Studio Help dialog objectproperties listbox messages List Box object

Use the parameters on this dialog as follows:
  • State field (read-only): Use this field to view the indexed individual messages. IWS numbers this field based on the Read/Search Tag type you selected:
    • Boolean: Provides two valid states, labeled 0 and 1
    • Integer: Provides 256 valid states, labeled 0 to 255
    • LSB: Provides 32 valid states (i.e., the 32 bits in an integer value), labeled 0 to 31
  • Message field: Enter the string to be displayed in the List Box object. You can include tags in a message by enclosing them in curly brackets (e.g., {tagname}).
  • Value field: Type a message value matching the specified Read/Search Tag value. (Also, the same value written to the write tag.)

    If you specify LSB for the Value field, IWS uses the value specified in the State field for both the Read/Search Tag and the write tag.

  • Text Foreground color field: Click to specify a color for the message text foreground. The color is displayed only when the message is not selected.
  • Text Blink checkbox: Click (check) to cause a message to blink, once per second, when it is selected.
  • Fonts button: Click to open the Font dialog, which allows you to change the characteristics (style, size, and so forth) of the message font.
  • Enable translation: Click (check) to enable translation during runtime using the Translation Tool.
  • Auto Format: When checked, if a message includes a decimal value enclosed by curly brackets (e,g, {1.2345}) or a project tag of Real type (see Message above), then the value will be formatted according to the virtual table created by the SetDecimalPoints function.

List Box object