The List Box () form object represents a list box. If you use a list as the source, you can select more than one item in the list using Shift-click or Ctrl-click. For other sources, you can only select one value from the list. Enter the name of the list box object in the Name field.

The Settings window contains the following sections.

In this section, you define the data source for the list box. The section contains a tree with a filtered view of the trees in the Application Builder and Model Builder windows. The nodes either represent some sort of data or have children that do. For a list box, the tree contains variables and parameters in the model and variables, such as a 1D array that you have added under Declarations, including Unit Set nodes. You can extend the list of available data nodes by clicking the Switch to Model Builder and Activate Data Access button () in the Source section header, which takes you to the Model Builder, and then selecting a node in the Model Builder branch whose data you want to access. With this button active, the Settings window of the selected node displays a Select Data Source check box (a green square) next to the settings that you can include. Click to select the check box to include the data as an available source node for list boxes.

When you select a node that represents data, the Use as Source toolbar button () below the tree becomes enabled. You can click it or, alternatively, press Enter, double-click, or right-click the node and choose Use as Source to add it as the selected source. You can also click the Create New Declaration and Use It as Source button () or the Create New Form Declaration and Use It as Source button () in the Source section header to create a new global or local (in the form) variable declaration for the list box and use it as the source. A Create and Use Declaration dialog box opens so that you can select the data type of the source (if applicable), its name, and its initial value (if applicable). The name cannot be in conflict with any existing variable declaration. Click the Edit Node toolbar button () below the tree to move to the corresponding node. If necessary, the program switches to the Model Builder.

After selecting a node as the source, the node appears as the selected source under Selected source.

In the Initial value list, choose a method to define an initial value for the list box. The options are First allowed value; From data source (the default, to use the value specified by the selected data source); and Custom value. For the Custom value option, a Value list shows the allowed values currently present for the form object, which depends on the selected available choice lists and their values. If the data source is a setting from the embedded model that has a list of allowed values, those values are also included in the Value list. If a selected initial value becomes invalid because it has been removed from the choice list, for instance, it is kept as an initial value with the text Invalid initial value followed by the value.

When the data source is a string array, the Initial value list is there along with the Empty array option that sets an empty array as the default for the selected source. There are also additional choices for how to select values. From the Select values in list, select Dialog to use a dialog to display the list box and enter a Dialog title in the field below, or select List box to use a multiselect list box. The Dialog option uses a list with buttons underneath, which users can use to add, delete, and move items in the list of selected items. This is suitable for a list with many items where you want to better control which items are selected (compared to a standard multiselect list box).

In the Selected list, add Choice List nodes that contribute allowed values to the list box. If the selected data source is a list with a set of allowed values, only a subset of the values can appear in the allowed values of the list box. All other values in the selected choice lists are ignored. Available Choice List nodes appear under Available. Click the Add Selected button to add the selected Choice List node to the list under Selected or click the Remove Selected button to remove a selected Choice List node from the list under Selected. You can also double-click a Choice List node to move it from Available to Selected and the other way around. Click the Add New Choice List () or Add New Form Choice List () button in the Choice List section’s toolbar to open a Choice List or Form Choice List window where you can define a new choice list under the global Declarations node or a local Declarations node under the Form node, respectively. Add the allowed values in the Value column and their corresponding names in the Display name column. Click OK to add the new choice list as a Choice List node () under Declarations and directly under Selected.

If you select a property that has a list of allowed values as the data source in the Source section, that property becomes a node initially placed in the Selected list. You can move it to the Available list, thereby clearing the list of allowed values. You can move it back again or add a custom choice list with values that also belong to the list of values for the property. If the property list and a choice list node are both in the Selected list, they will be merged. Identical values pick the description from the first item in the list under Selected. In this way, you can rename one of the items in the property list. If you decide to switch the source to another property in the embedded model that also has a list of allowed values, the previous property list node is removed from both the Available and Selected lists, and the new node is added to the Selected list.

The need to specify the alignment is most obvious when working in the grid mode, as it controls how the form object is aligned in its grid cell. Aligning the form object can be useful in the sketch mode too. You can then use the alignment tools on the Arrange menu in the Form toolbar’s Sketch section. When running the application in any client other than the Windows client, the form objects may not be positioned exactly as seen in the form windows. This is because the form objects may have a different size in other clients, giving them a slightly different positioning. Specifying the alignment ensures that the form objects are aligned as you want them to be in all clients.

You can also specify the width and height of the list box. Enter a width (in points) in the Width field and a height (in points) in the Height field. If you have chosen Fill from the Horizontal alignment list, you can instead specify a Minimum width. Choose Automatic to compute the minimum width automatically (typically, this means a minimum size of 0) or choose Manual to specify a minimum width in the text field underneath. If you have chosen Fill from the Vertical alignment list, you can instead specify a Minimum height. Choose Automatic to compute the minimum height automatically (typically, this means a minimum size of 0) or choose Manual to specify a minimum height in the text field underneath.

Additionally, in the sketch mode, you can specify the absolute position of the list box using the Position x and Position y fields. In the grid mode, you can position the object in the grid and see the grid position as the Row, Column, Row span, and Column span values.

Under Cell margin (in grid mode only), you can control the margins around the form object. By default, the margins are taken from the parent form. From the Cell margin list, choose:

From the Text color list, select a color to use for the text: Inherit (the default; the form object then uses the setting from the Form it is located in), any of the predefined basic colors, or Custom, which makes it possible to select a custom color from a color palette.

The font and the font size for the text use the font settings from the Forms node by default. Select a font from the Font list: Default font or any of the available fonts. If needed, choose or enter a font size (in points) in the Font size combo box. The default font size is Default size.

You can also select the Bold check box to use a boldface font or the Italic check box to use italics (an italic font).

Under State, you can control the initial state of the list box when users run the application. By default, the list box is visible and enabled. Clear the Visible or Enabled check box if you want to make the initial state so that the list box is hidden or unavailable. You can then make it visible or enable it using a method. In the Form Editor, the state of the form object is indicated by a change in its appearance. Objects that are hidden become visible when selected in the Form Editor.

You can specify a method or command sequence that the application runs when the data in the list box changes. The On data change list contains None (the default) and any available methods or command sequence. You can add the following types of events by choosing from the Create Global Method menu () to the right of the On data change list:

There can only be one local method and one command sequence so if you add one or both of them, the menu will instead contain Remove Local Method () and Remove Command Sequence (), respectively. Click one of them to delete the local method or command sequence.

The selected method in the On data change list then changes to the created method or command sequence. You can also Ctrl+Alt-click the list box object or right-click it to create a local method or (by choosing Edit Method or Edit Local Method) to open the method associated with the command. To open the selected method or command sequence, click the Go to Source button (). The focus then moves to the method’s editor window or the Command Sequence dialog box, respectively.