A List is a graphical user interface that allows the user to select one item from a list contained within a static, multiple line text box. The user clicks inside the box on an item to select it. The options that appear in a list box widget can be defined in two ways:

• Value List - The application's author defines a list of values which will appear in the drop down menu.
• Lookup List - The widget references a field in another collection tab. The drop down menu displays values based on the records that exist in the referenced collection.

Adding a List Box to the Form

1. In the Form Editor canvas, drag the from the Form Widgets palette onto the form canvas. A new List Box widget is added in the canvas.
   
2. Enter a Label for your List Box. Notice that the Data Field in the data section of the form editor is now populated with the label name but without spaces.
   
   The Data Field name should not contain any spaces and should be a unique name within the collection.
3. The Properties section of the form editor will allow you to customize the data properties of the widget.
   
4. Under Data Type select the type of data that will be used in your List Box. The most commonly used data type is string or text.
5. The Required Field radio button allows you to determine if the field needs to be filled out before a user is able to save the record. If the field is marked as a required field, it will be designated with a red asterisk (*) in the form.
6. The Display this field in the default Collection View checkbox allows you to add this field as a column in the collection tab's view without having to enter the View Editor.
7. Select either the Simple or Calculated radio button. Simple will allow users to choose a value from the drop down list while calculated will populate the list box based on an expression defined using the Expression Builder. If you select the Calculated radio button the Properties section will change, allowing you to enter an expression in the Value box.
   
8. For Simple list box widgets, you can define the values which will appear in the drop down list by clicking on the button to the right of Possible and Default Values.
   
   The Possible and Default Value window will open. Information on how to set up the List Box's options for Value List and Lookup is listed in the sections below.
   
9. Widget display properties for the list box can be customized by clicking on the Widget tab in the Properties section of the Form Editor.
   
   
10. The Number of rows to display menu allows you to select the number of rows that appear in the list box before the user needs to use the scroll bar.
11. Authors can define Conditional Styling options by clicking on the icon next to Condition Style.
    
12. Once you have finished defining your List Box click Save to save the changes to your form. Refer to the section on Version Management for more information.
13. Click Exit to close the Form Editor and to return to the Collection page.

Populating the List Box entries manually (Value List)

1. In the Possible and Default Values window, select the Value List radio button.
2. Click on the Add button to add options to your List Box. Options can be deleted by clicking on the Remove button.
   
3. Click on the Key column for Option1 and enter the name of the option. When you click out of the Key column, the Value column will automatically update to match the Key column. You can define the Value to be different from the Key by clicking on the Value column and entering a name. The Key is what is displayed in the widget itself while Value is what is actually stored in the database or seen in the collection's view.
   
4. A list box's options can be re-ordered by clicking on the Up or Down buttons.
5. Clicking on the Default Value radio button will display a textbox where you can define the default value for this widget.
6. Click Done when you are done populating your list manually.

Populating the List Box using other data sources (Lookup)

1. In the Possible and Default Values window, select the Lookup radio button.
   
2. To set the collection which the widget will reference, click on the button to the right of Linked Collection. From the Select Collection window, choose the appropriate collection and then click Select.
3. Click on the button to the right of Filter to open the Filter and Sort window. Here you will define the filtering criteria, if any, which will be used to choose the options for the list box widget from the list of records in the linked collection.
   
4. To select the field which will appear in the list box drop down list click on the button to the right of Display Field.
5. In the Select a Field window, click on a field to select it.
6. Click on Done when you have finished defining the lookup criteria for the list box widget.