Control : List

Page Status: Beta

Back to Controls

The List control displays an interactive list of values, either as a multi-line list box or a combo box.

List control as a combo box. List control as a list box.

Contents

Examples

The following examples are intended to be used with sample code that you can import into your Bungee Builder workspace from the Design page's Home tab. Each example is intended to build upon the previous example to provide you with a complete 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 at first may be challenging, but will 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 integer. Whatever value is selected 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. If you wish a value to display an alternate name instead of the actual value, the Enumeration property provides you with an option to set a Display string for each enumeration 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 Adapter linking the View element (the List control) to the Model element (the primitive field). The following diagram shows this relationship.

Click for larger image  Run Now

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 label in the List (similar to using Enumeration in Ex1). 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 Adapter exists between the two, as shown in the accompanying Model-View-Adapter 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.

Click for larger image  Run Now

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 ListConnection, 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 complex objects. Because complex 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.

This creates a new ListElementConnection and opens it in the Design Editor. You then assign a field from the class to display.

If you later wish to edit the ListElementConnection, it is found 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.

As with all control connections, the ListElementConnection is accessed by the List control by way of an adapter. The label binding for the List control is actually an adapter, set on the control's Element property (Adapter tab). The default adapter assigned to all List controls is a native connection adapter named ListElementAdapter.

If you have two or more List controls bound to collections of the same element type, and want each to display a differently formatted label for the element class, then you need to add a custom Connection Adapter to the TypeLib, and assign it to the List control. Then you can add a custom ListElementConnection to the element class and associate the connection with the custom Connection Adapter. (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 Connection Adapter (ListElementAdapter) has been used to create a ListElementConnection,which can be found in the Person class.

In the diagram, note how the standard Control Adapter is now accompanied by a Connection Adapter, showing the ListElementConnection that assigns the List control's label to display the firstName field of the (Person) element class.

Click for larger image  Run Now

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 Connection Adapter for each List control assigns the control to use a different ListElementConnection. The Fullname ListElementConnection is configured to display firstName lastName. The Lastnamefirst is set to display lastName, firstName. In the example code, the two ListElementConnections are in the Person class.

Click for larger image  Run Now

Example 4: Working with selectedElement

Concept Overview

The selectedElement for a List control (or a FormList control) allows you to use 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 whatever object the end user has selected in a list by using a ListConnection with a default Connection Adapter.

To use this design pattern, you create a new field of the same type as the collection to which the List control has been bound. 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 create the ListConnection:

You then configure the ListConnection to assign the selectedElement to the external field. Enable the Linked property in the connection so that any changes made to the external field are synchronized with the collection's selectedElement.

Example: Ex4_PersonCollectionWithSelection

The above concepts are implemented in the example code. The List control is bound to the People field, which is a collection of Person objects. In order to use selectedElement for that collection, the creators of this example added a new field called selectedPerson, which is based on the Person element class. A ListConnection has been configured to link the selectedPerson field with the selectedElement in the List control.

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.

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.

Click for larger image  Run Now

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 use Bungee Logic to perform arbitrary logic at the time that an end user selects an item displayed a List (or a FormList). To do so, you add View code to the ListElementConnection's selectedElement section by clicking the 'V' (Add View Code) button for the selectedElement section of the connection. 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).

Ex5_PeopleCollectionWithViewSelection provides a very simple example of this by assigning a calculated value to a field whenever the end user selects an item in the List. This example is almost exactly the same as the previous example (it inherits from Ex4_PersonCollectionWithSelection), with two changes: a string field named selectedPersonComputedText has been added to the example class, and the ListConnection has been customized with View code that computes a custom text string and assigns it to the selectedPersonComputedText field. (The View code also assigns the selectedElement object to the selectedPerson field.) The example user interface displays the calculated field in a Label control (in blue).

As you inspect the sample code, be sure to investigate the View code in the connection. It contains comments to explain each line of Bungee Logic.

Click for larger image  Run Now

Note Similar to View code, you can also use Model code in a connection. Use Model code to execute logic based on a change in the data model, such as a change in the value of a field. Use View code to execute logic based on a user interface event, such as a the user making a selection in a List control.

Example 6: Enabling Interaction Shortcuts (Ex6_EditPersonCollection)

You can use Function Adapters 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 Adapters 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 Adapter. You configure Function Adapters following the same design pattern that you use with Form Adapters (as you learned in Bungee Essentials Tutorial #2). First, add a Function Adapter to your TypeLib. Next, add the Function Adapter to a Function's Adapter 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 Adapter to the Double Click property (Adapter tab).

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 Adapter 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.

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 RemoveFunctionAdapter. To configure this, you assign Bungee Connect's native RemoveFunctionAdapter (on the Dependencies tab, under TypeLib: Meta) to the desired function's Adapter List property (General tab). As documented in the Reference section below, the function must include a selectName argument, which is used to identify the currently selected item(s). Complete the relationship by assigning the RemoveFunctionAdapter to the List control's Remove Function property (Adapter List tab).

The example code has been configured so that the Delete key calls a 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.

Click for larger image  Run Now

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 Adapters, as shown in the diagram below:

  • The Control Adapters are implicit adapters that result from binding a control to a field or function.
  • Both forms have been assigned a Form Adapter in their Adapter List property. The Form Adapters exist in the TypeLib (not the actual person class), and their names correspond directly to the forms that use them (Detail, NewPersonDetail).
  • The Connection Adapters are used in conjunction with the List control's Label property in the examples to show how to transform text in the View.
  • The DoubleClick Function Adapter, 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.

Click for larger image Run Now

Reference

Frequently-used Options

Some of the most commonly used properties that apply to this control are:

  • Behavior tab:
    • Size: When you set this to 1, the List control displays as a combo box. Set Size to any other value to display as a standard list box (default).
    • Multiple Select: Enable this option if you want the end user to be able to use Ctrl-Click and Shift-Click to select more than one item in the list.

Limitations

For better browser compatibility, and to provide a more native look and feel, Bungee Connect's List control actually wraps the HTML-native SELECT tag. The SELECT tag object has some intrinsic limitations. For example, dragging-and-dropping items to/from an HTML List is not possible (and therefore, is not supported with Bungee Connect's List control). Virtual list capability is also not supported. In addition, the List control can only display simple strings for each item in the list, thus limiting the List interface to displaying simple text. If you need a List control that supports drag-and-drop, virtual lists, and other media and layout capabilities, use the FormList control.

Supported Types (Control Adapter)

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.

Property Adapters

Name Summary
Tooltip Displays the Tooltip as the user moves the mouse within the List area.

Connection Adapters

Name Default Summary
Selection ListAdapter Selection control for the List. You can respond to selection by end-users as well as set initial selection when bound to an application object.
Element ListElementAdapter Used to control the text to be produced for each item in the List as it is associated with the item within the application object.

Connection Adapter: Selection

The Selection connection adapter is invoked in the application object context, not the context or scope of just the field that is tied to the List control itself. That way, the selection for that particular field can be managed in a parent context that is able to handle the specific semantics for that member. The parent context is always the root of the path used to connect the List to the field (see the Path property on Control)

Field Type Field Name Description
string selectName The collection type can manage multiple selected sets where each selection is identified with a string name. You can set selectName to a specific selection that is desired. If selectName is not set, then default is the selected set name used by the List control when setting selection on the collection. Typically, you do not need to set this value; if it is not associated with a value then the default selected set is used.
Data selectedElement The selectedElement is set when the end user selects an item in the List control. Because items in the List control can be primitive or Object types, the type of this field is Data. The Data member can contain either primitive or complex Object values.
boolean setSelectOnInit If an application object field is associated with the selectedElement field (see above), then setSelectOnInit determines if that field is set when the List control is first connected to the Model.

Connection Adapter: Element

Field Type Field Name Description
string Label The label is the value used by the List control for displaying each item from the primitive or Object collection types. The Element connection adapter comes into play only when the control adapter detects a collection type on the model side (the application object collection member tied to the List control). For complex Object collections, each element in the collection is “connected” through the Element connection adapter in order to extract the correct association to the Label field. For example, many different subclasses of Object can implement custom connections of the same adapter type.

Function Adapters

Name Default Summary
Double Click <not set> The Double Click function adapter on the application object is called when a user double-clicks an item in the List control. No attempt is made to call the Double Click function adapter on the application object if the adapter is <not set> for this property.
Remove Function <not set> The Remove Function function adapter on the application object is called when a user presses the Delete key on a selected item in the List control.

Function Adapter: Double Click

Field Type Field Name Description
long index This is the index of the item on which the end user double-clicked.
Data Item This is the item that was double-clicked. The value is of type Data because a List control can be tied to either primitive or complex Object type values. Simply assign the Item value to a known or expected type; also, the target function on the application object can contain this signature but with the expected type for this argument being the argument type. For example, if the expected type for the Item is Person, then the signature on the application object may look something like this: showDetail(long index, Person item);

Function Adapter: Remove Function

The Remove function adapter (if set on the List control property) is called when an end user selects an item(s) and presses the Delete key. The List does not remove the item(s) from the collection; instead, the Remove function adapter that is implemented on the application object context that contains the collection field, is called to remove the item.

Field Type Field Name Description
string selectName This is the name of the selected set involved in this item removal. selectName allows the function to differentiate between selected sets when deciding to remove an item from the Model side of the connection (the application object collection).
boolean shiftKeyDown This indicates to the function that the user intends to permanently remove the item, not just remove it from the current collection. It is up to you (as the implementer of the function adapter of the application object) to decide whether to remove the item from the selectName selected set from the collection. You can query the collection (with the selectName) for the item(s) involved in that selected set (see Collection).

 

Associated Properties

Common Properties Index

Specialized Properties

Unique Properties

  • None
Retrieved from "http://docs.bungeeconnect.com/wiki/index.php/Control_:_List"
    Copyright © 2005 - 2007 Bungee Labs. All rights reserved.