Control : List 
The List control encapsulates HTML <select> tag functionality within a Bungee Connect control.
List control as a combo box. |
List control as a list box. |
Overview
The List control displays an interactive list of values, either as a standard List box (the default setting) or a Combobox. To change the List control to a Combobox, on the Behavior tab of the Property Editor, set the Size property to 1. Setting the Size to any other value to changes the display to the default (a standard list box).
If you want your end users to be able to use Ctrl-Click and Shift-Click to select more than one item in a list, enable the Multiple Select property on the Behavior tab.
Capabilities
Use the List control to:
- Display items listed in a primitive, such as a string with an enumeration (Example 1)
- Display items in a collection of primitives (Example 2)
- Display items in a collection of objects (Example 3)
- Programmatically manipulate items a user selects in a List (Example 4)
- Execute logic based on a select event (Example 5)
- Enable user interaction shortcuts (Example 6)
Limitations
The List control has limitations applicable to all browser types, as well as some specific to Internet Explorer.
General Limitations
In general terms, the limitations of the List control are those you encounter using the HTML <select> tag.
- There is no drag and drop from or to this control as the HTML <select> tag does not provide events for drag and drop
- Creation of virtual lists is not supported
- Items in a List cannot be bolded
- Images cannot be displayed in a List, only simple strings can be displayed
Note Drag-and-drop, virtual lists, and other media and layout capabilities (such as the ability to display images in a list) are provided with the FormList control.
Internet Explorer Specific Limitations
There are some limitations with the List control that are Internet Explorer specific:
- Calling deselect on a Collection bound to a List Control correctly deselects the selected item in both FireFox and Safari, but not Internet Explorer
- When the List control is first initialized, there appears to be an item selected in the list. This is not really so, however. To avoid this, you must overtly set an item to be selected upon initialization.
Requirements
The requirements for this control vary with what you are trying to accomplish. If you want to display a list of primitives, you need only attach the control to the proper data type as in Examples 1 and 2. If you want to display data from more complex data types, the List control requires you to use both interfaces and adapters.
In the examples below, the List control requires the use of the following adapters:
- ListElementAdapter (Example 3)
- ListAdapter (Example 4, Example 5)
Note In the scenarios provided in the examples, you add the adapters to a control by binding either labels or selections. This method does not require you to overtly add the interfaces needed for the adapters, however, you can tell which interface is added with the adapter, as the interface name is provided with the adapter title (for example ListAdapter # ListInterface).
Examples
The following examples are intended to be used with sample code that you can import from the Design page's Home tab into your Bungee Builder DesignGroup. Each example is intended to build upon the previous example in order to provide you with a solid understanding of how to use this control.
Examples 1-4 provide a solid introduction to using the List control. Examples 5 and 6 present more advanced concepts that allow you to increase the sophistication of your Bungee-powered applications significantly.
Example 1: Binding to a Primitive Field (Ex1_PickFruit)
You can bind the List control to a primitive field, such as a string or an Runtime Type : Types : int|integer]]. Whatever item a user selects from the list becomes the current value of the field. You assign selectable items to the list through the primitive field's Enumeration property on the General tab of the Property Editor. The Enumeration property provides you with an option to set a Display string for each enumeration value, in case you want a list item to display an alternate name rather than the actual value. In the example, the list control appears as a combo box because its Size property (on the Behavior tab) has been set to 1.
When you bind the List control to the primitive field, Bungee Connect automatically configures a Control Interface linking the View element (the List control) to the Model element (the primitive field). The following diagram shows this relationship.
Example 2: Binding to a Collection of Primitives (Ex2_VegetableCollection)
You can bind the List control to a Collection of primitives. By doing so, each primitive element in the collection becomes a selectable item in the List (similar to using Enumeration in Example 1). In the example, you have a field called veggies, which is a Collection of strings. The binding between the veggies collection and the List control means that a Control Interface exists between the two, as shown in the accompanying Model-View-Interface diagram.
Note In order to ensure that the collection contains values at runtime, the designers of this example overrode the OnCreate function on the Ex2_VegetableCollection class. The override simply adds some string values to the veggies collection each time you simulate (or run) the application.
Unlike the previous example, when you select an item in the List, the selected value does not become the value of the field to which the control is bound. Instead, you must use a ListAdapter, as explained in Example 4.
Example 3: Binding to a Collection of Objects (Ex3_PersonCollection)
You can also bind the List control to a collection of objects. Because objects typically have more than a single field, you must assign which field the List displays at runtime, otherwise the list appears to be empty. Use the control's Bind Label option to do this.
.png)
This creates a new ListElementAdapter and opens it in the Design Editor. You then assign a field from the class to the label element of the ListElementAdapter so that the values from the field you assign to label can appear in the List control at runtime.
If later, you wish to edit the ListElementAdapter (to change the field whose values appear in the List), you can find the adapter in the element class for the List control, that is, the class of objects contained in the Collection to which the List control has been bound.
The List control uses an interface to access the ListElementAdapter (this is how all controls access adapters). The adapter's label binding for the List control is actually an interface, set on the control's Element property (on the Interface tab). The default interface assigned to all List controls is a native adapter interface called ListElementInterface.
If you have two or more List controls bound to collections of the same element type (say an object called Person), and want each List control to display a differently formatted label for the element class (Person), then you need to add a custom Adapter Interface to the project that contains the class, and assign the interface to the List control using the Element property. Then you can add a ListElementAdapter to the element class (Person) and associate the adapter with the custom Adapter Interface. (Example 3.2 provides a sample configuration.)
Example 3.1
In this example, the List control is bound to the People field, which is a collection of objects based on a custom class called Person. The List's label has been bound to the firstName field of the Person class. The default Adapter Interface (ListElementInterface) has been used to create a ListElementAdapter,which can be found in the Person class.
In the diagram, note how the standard Control Interface is now accompanied by an Adapter Interface, showing the ListElementAdapter that assigns the List control's label to display the firstName field of the (Person) element class.
Example 3.2
In this example, there are two List controls on the form. Because both Lists are bound to the same collection, when you select an item in one control, the corresponding item in the other also indicates that it is selected.
The two Lists display their labels differently because the Adapter Interface for each List control assigns the control to use a different ListElementAdapter. The Fullname ListElementAdapter is configured to display firstName lastName. The Lastnamefirst is set to display lastName, firstName. In the example code, the two ListElementAdapters are in the Person class.
Example 4: Working with selectedElement
Concept Overview
Use the ListAdapter's selectedElement to implement a simple yet powerful design pattern in Bungee Connect. At runtime, when a user selects an item in a List control, you can programmatically manipulate the object that item represents by using a ListAdapter with a default ListInterface adapter interface.
To use this design pattern, you create a new field of the same type as the collection to which you bound the List control. This new field functions as a workspace object external to the original collection, allowing you to provide user interfaces or perform programmatic operations on the selectedElement.
Use the List control's Bind Selection option to add the ListAdapter to your class:
You then configure the ListAdapter to assign the selectedElement to the external field. Select the Linked property in the adapter so that any changes made to the external field are synchronized with the collection's selectedElement.
.png)
Example: Ex4_PersonCollectionWithSelection
The above concepts are implemented in the example code.
Note The class Ex4_PersonCollectionWithSelection in the sample code inherits from Ex3_PersonCollection. Although you do not explicitly see the People collection, the field is inherited from the Ex3_PersonCollection class.
The List control is bound to the people field, which is a collection of Person objects. In order to use selectedElement on the ListAdapter for that collection, the creators of this example added a new field called selectedPerson, which is based on the Person class. A ListAdapter has been configured to link the selectedPerson field with the selectedElement in the List control.
For this example, the selectedElement design pattern has been used to provide a user interface for editing the selectedElement. At right of the List control on form Ex4_PeopleSelection you see the Detail form from the Person class embedded in a DynamicForm control.
Because the Dynamic form is bound to the selectedPerson field, each time an end user selects an item in the List at runtime, the selectedElement re-populates the selectedPerson field and the Detail form updates. When the end user makes changes in the Detail form, the changes to the selectedPerson field are automatically made to the selectedElement in the collection as well.
Example 5: Executing Logic on a Select Event (Ex5_PeopleCollectionWithViewSelection)
In the previous example, you learned how to use selectedElement to link an external object with an object in a collection. You can also add Bungee Logic to a adapter to perform programmatic updates that are triggered by an end user selecting an item displayed in a List (or a FormList). To do so, you add View code to the ListAdapter's selectedElement section by clicking the V (Add View Code) button for the selectedElement section of the adapter. Use View code whenever you want to perform logic that is driven by a View event (such as a user selecting an item in a List control).
The Ex5_PeopleCollectionWithViewSelection class provides a very simple example of this extra logic by assigning a calculated value to a field and displaying that value whenever an end user selects an item in the List. Example 5 modifies Example 4 only slightly (Example 5's class inherits from Ex4_PersonCollectionWithSelection), containing only two changes: a string field named selectedPersonComputedText has been added to the example class (to store the caluculated value), and the ListAdapter contains View code that computes a custom text string and assigns the string value to the selectedPersonComputedText field. (The View code also assigns the selectedElement from the adapter to the selectedPerson field.) The calculated text appears (in blue) within a Label control.
As you inspect the sample code, be sure to investigate the View code in the adapter. It contains comments to explain each line of Bungee Logic.
Note Similar to View code, you can also use Model code in an adapter. Use Model code to execute logic based on a change in the data model, such as a change in the value of a field. There is an example of Model code available on Example 3 of the DynamicForm control.
Example 6: Enabling Interaction Shortcuts (Ex6_EditPersonCollection)
You can use Function Interfaces to assign functions to common user interactions, such as double-clicking an item, or pressing the Delete key.
This example inherits from Ex3_PersonCollection, but has its own form, as well as three functions. The addPerson function is not discussed here because it does not directly interact with the List control. The other two functions, showPersonDetail and removePersonWithPrompt, both employ Function Interfaces to enable double-clicking and the delete key in conjunction with the List control.
Enabling Actions on Double Click
You can perform a function on any object displayed in the List control by using the Double Click function interface. You configure function interfaces following the same design pattern that you use with form interfaces (as you learned in Bungee Essentials Tutorial #2). First, add a function interface to your project. Next, add the function interface to a Function's Interface List property (General tab). As documented in the Reference section below, your function must include two inbound arguments (index and item) in order to identify which item from the collection to affect. Finally, select the List control and assign the function interface to the Double Click property (Interface tab). These steps are covered in more detail in Using Function Interfaces.
In the example, the end user can bring up a detail form by double-clicking any item in the List. The showPersonDetail function has been connected to the List control through a Function Interface named DoubleClick. The function uses the open dialog command to open a form called Detail (located in the Person class) that displays the Person object that was double-clicked in the List.
Enabling the Delete Key to Perform an Action
You can assign the Delete key to perform an action by connecting the List control to a function using the RemoveFunctionInterface. In this example, a function interface called Remove has been added to the List project and assigned to the List control using the Removed property (Interface tab). As documented in the Removed property, the function must include a selectName argument, which is used to identify the currently selected item(s). Complete the relationship by assigning the RemoveFunctionInterface to the List control's Removed property (Interface List tab).
The example code has been configured so that a computer's Del(ete) key calls the removePersonWithPrompt function. The function uses the dialog message command to present the user with a confirmation dialog. When the user clicks the OK or Cancel button in the dialog, the function's confirm var is assigned a value of true or false. When the user selects OK (confirm = true), the function calls the People collection's removeSelected function to remove the selected item(s). Note that this same function is also bound to the Remove button, which provides the user with a visual interaction element in the user interface in addition to the Delete key.
Example Helper Classes
The examples above incorporate the following helper classes and other supporting objects.
Person
This class defines the Person object type, which is used in examples 3-6 above. Besides defining the two fields (firstName, lastName) and two forms (Detail, NewPersonDetail), it also defines some interfaces, as shown in the diagram below:
- The control interfaces are implicit interfaces that result from binding a control to a field or function.
- Both forms have been assigned a form interface in their Interface List property. The Form Interfaces exist in the project (not the actual person class), and their names correspond directly to the forms that use them (Detail, NewPersonDetail).
- The adapter interfaces are used in conjunction with the List control's Label property in the examples to show how to transform text in the View.
- The Double Click function interface, used in Example 6, is indirectly related to the Person class in that it provides the index and item arguments from the People collection, which is a collection of Person objects.
Reference
Supported Types
| Type | Summary |
|---|---|
| Primitives | Primitive type fields within application objects that are connected to the List control must have an enumeration defined in order for the List control to populate its items correctly. For example, a string field type called fruit could have its enumeration property set to {Apple, Orange, Pear} in order for those values to show up as items in the List control. The currently selected enumeration represents the value of the field within the application object. |
| Collection<primitives> | Primitive type fields within an application object that are connected to the List where the field is a collection (the field's Is Collection property is set to true). For each item in the field’s collection, a corresponding item in the List is displayed. If the collection changes, the List view auto-tracks those changes and updates the List control on the remote client appropriately. |
| Collection<Object> |
Complex Object type fields within application objects that are connected to the List control where the field is a collection (the field's Is Collection property is set to true). For each item in the field’s collection, a corresponding item in the List is displayed by extracting key attributes from the object’s structure. For example, if an object in the collection is of type Person with firstName and lastName fields, you can define how to extract those fields from the object when computing the text for the List item that represents that object. If the collection changes, including the internal members of the object used in text calculation, the List view auto-tracks those changes and updates the List control on the remote client appropriately. Collections of type Object include any subclass of Object as well. For example, Collection<Person> can be tied to the List, where Person subclasses (or inherits) from Object and represents any application object in your project. |
Default Interfaces
| Type | Summary |
|---|---|
| ListInterface | An adapter interface, assigned to the control through the Selection property |
| ListElementInterface | An adapter interface, assigned to the control through the Element property |
Adapters
| Type | Summary |
|---|---|
| ListAdapter | Enables control over the selection of items displayed in a List control. You use a ListAdapter to set initial selection in the control, as well as to respond to end-user selection of items in a List. |
| ListElementAdapter | Provides the text that appears as a label for each item in a List control you have bound to a collection. You add the adapter by clicking Bind Label on the List control. This binds the label that appears in the List control to the application object that is the type of the items stored in the collection. |
Properties
Specialized Properties
- Allow Remove
- Close On Double Click
- Double Click
- Element
- Empty Value Allowed
- Empty Value Text
- Multiple Select
- Removed
- Selection
- Single Select
- Size
Unique Properties
- None
