571 CHAPTER Using List Controls IN THIS CHAPTER Understanding list controls Providing data to list controls Using dynamic data providers Controlling list item labels Using list control events and properties Handling user data selections Using custom item renderers M ost Flex applications are designed for the purpose of presenting and managing data in some form. As a result, one of the most pop- ular families of visual controls in the Flex framework includes those known as list controls. A list control is defined as a component that has a dataProvider property that enables you to populate the control with dynamic data. The data provided to a list control can be in the form of either hierarchical or relational data, and the type of data you want to present frequently determines which control you use. In addition to being able to display relational or hierarchical data, list con- trols have a common set of properties, methods, and events that enable the user to select one or more items with mouse and keyboard gestures. The Flex 4 SDK includes both the older MX list controls such as DataGrid, AdvancedDataGrid, and OlapDataGrid and newer controls based on the new Spark component architecture: l The List component. This component behaves by default like an HTML <select> control and displays data items to the user in a list box. After you learn how to use the List control, you have most of the information you need to use other such controls. You can populate controls with data, listen for events indicating that the user has selected or started to drag data, set common styles, and so on. It supports the Spark layout architecture, so you can display a horizontal or tile layout instead of the default vertical list. l The DropDownList and ComboBox components. These compo- nents also behave like an HTML <select> control but use a drop- down list instead of a static list. l The ButtonBar component. This component has the same appearance and behavior as an MX ToggleButtonBar, presenting a set of ToggleButton controls horizontally, but is controlled programmatically just like other Spark list controls. 26_488959-ch19.indd 57126_488959-ch19.indd 571 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part III: Working with Data 572 On the Web To use the sample code for this chapter, import the chapter19.fxp project from the Web site files into any folder on your disk. n In this chapter, I describe in general terms how to use all list controls. I include information on how to populate these controls with data, how to control data presentation with custom generation of item labels and renderers, and how to handle events indicating that the user wants to select and manipulate data. Cross-Reference The unique capabilities of other list controls, including the MX DataGrid, TileList, and HorizontalList, and the new Spark components, are described in Chapter 20. n Table 19.1 describes the components that have the capability to display dynamic data and support user interaction using the list control model. In the Architecture column I show which component architecture the most recent version of the component implements. TABLE 19.1 The List Controls Control Architecture Description Advanced DataGrid MX This component implements all the features of the MX DataGrid control but adds the capability to group and aggregate data and can sort on multiple columns. This component is part of the Flex Data Visualization components and is available only with a Flash Builder Premiere license. ButtonBar Spark This new component presents Spark ToggleButton objects horizontally. The appearance and behavior are similar to the MX ToggleButtonBar, but the application programming interface (API) follows the list model, implementing the change event and selected Item and selectedIndex properties. ComboBox Spark This component presents a drop-down list of simple string values. The presentation of this component is similar to an HTML <select> con- trol that has its size property set to 1, but enables the user to enter an arbitrary string instead of selecting an item from the list. DataGrid MX This component presents a grid with multiple rows and columns. It is used to present data received from a server-side database or other data source that uses the spreadsheet-like rows-and-columns structure of relational database tables. DropDownList Spark Extended from the Spark List control, this control shows a drop- down list from which the user can select a value. Its layout property enables you to lay the list out with vertical, horizontal, or tile layout. 26_488959-ch19.indd 57226_488959-ch19.indd 572 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 19: Using List Controls 573 Control Architecture Description Horizontal List MX This component presents a horizontal list of data items, typically ren- dered with a custom item renderer. (For the Spark architecture, use a List with layout set to HorizontalLayout.) List Spark This component presents a list box of data items. By default, the presenta- tion of this component is similar to an HTML <select> control that has its size property set to a value greater than 1. Its layout property enables you to lay out the list’s items with a Spark layout object such as HorizontalLayout or TileLayout. OlapDataGrid MX This component expands on the AdvancedDataGrid and supports pre- sentation of results from an Online Analytical Processing (OLAP) query. TileList MX This component presents a grid of data items, typically rendered with a custom item renderer. (For the Spark architecture, use a List with layout set to TileLayout.) Tree MX This component presents hierarchical data, commonly supplied by the contents of an XML file. In addition to the components listed in Table 19.1, the Flex SDK includes a set of MX-based list controls designed for use in Adobe AIR applications. These controls provide the user with the abil- ity to inspect and manipulate files and directories in the local file system and cannot be used in Flex applications that are deployed over the Web. They include the FileSystemList, FileSystemComboBox, FileSystemDataGrid, and FileSystemTree components. Most of the information in this chapter and in Chapter 20 about list and DataGrid controls applies equally to these AIR-based controls, but these controls add functionality that enables them to populate their data from the directory and file contents of the local file system. They also imple- ment additional properties and methods that are designed to support their unique purpose. Note Other MX components extend a class named ComboBase and therefore must be considered members of the family of list controls as well. The ColorPicker control is designed to enable selection of a color value from a grid of “Web-safe” colors, and the DateField control presents a pop-up calendar control. The components aren’t often thought of as list controls, but they support the same set of properties, methods, and events as their cousins. In the Flex 4 SDK, there are no Spark equivalents to these components. n Each list control has its own unique visual presentation and behavior. As the developer, you select the control most suited to your application’s requirements. Figure 19.1 shows examples of the List, DataGrid, and DropDownList controls, each using the same set of data as its data provider. On the Web The application displayed in Figure 19.1 is available in the Web site files as ListControls.mxml in the chapter19 project. n 26_488959-ch19.indd 57326_488959-ch19.indd 573 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part III: Working with Data 574 FIGURE 19.1 Commonly used list controls Using Data Providers The data you provide to a list control must be in the form of an ActionScript object, but for most purposes you typically provide a set of data that’s been wrapped in one of the data collection classes: either the ArrayList or ArrayCollection classes for data that’s in rows and columns or the XMLListCollection class for hierarchical data. The Spark and MX list controls have the same basic rules for their data providers: the data must be provided as an ordered data collection. But the Spark controls ( List, DropDownList, and ComboBox) specify that the data object must implement the IList interface, whereas the MX con- trols accept any ActionScript Object. In practical terms, this means that the MX DataGrid and other related controls can accept a raw Array as their dataProvider, while the new Spark con- trols require an ArrayList, ArrayCollection, or other class that implements the interface. The List, DropDownList, and ComboBox controls are distinguished from the DataGrid and its related controls in that they present only a single column of data. They can present data from a collection of complex objects, but by default they present only one value in each list item. In con- trast, the DataGrid control is designed to present data in multiple columns. 26_488959-ch19.indd 57426_488959-ch19.indd 574 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 19: Using List Controls 575 Using hard-coded data providers You can embed data in a Flex application for use by either a specific instance of a list control or as a separate data object that’s then linked to a control through a binding expression. Hard-coding means that you declare actual data in the code, rather than retrieving it from an external data source at runtime. Caution As described in Chapter 18, when you embed data in a Flex application, the compiled application file expands accordingly. You should embed data only when it’s a small amount of content and won’t change during the lifetime of the application. n Nesting hard-coded data in a data provider When using a list control, you can nest hard-coded data in the declaration of a list control’s data- Provider by declaring the property with child-element syntax rather than attribute syntax. The following code presents a List control populated with a hard-coded data provider containing an ArrayList of simple String values: <s:List id=”sizeList”> <s:dataProvider> <s:ArrayList> <fx:String>Small</fx:String> <fx:String>Medium</fx:String> <fx:String>Large</fx:String> </s:ArrayList> </s:dataProvider> </s:List> You also can declare the dataProvider with hard-coded collections of complex objects by nest- ing multiple <fx:Object> declarations within the <s:dataProvider> tag set: <s:List id=”stateList” labelField=”stateName”> <s:dataProvider> <s:ArrayList> <fx:Object> <fx:stateName>California</fx:stateName> <fx:capitol>Sacramento</fx:capitol> </fx:Object> <fx:Object> <fx:stateName>Oregon</fx:stateName> <fx:capitol>Salem</fx:capitol> </fx:Object> <fx:Object> <fx:stateName>Washington</fx:stateName> <fx:capitol>Olympia</fx:capitol> </fx:Object> <s:ArrayList> </s:dataProvider> </s:List> 26_488959-ch19.indd 57526_488959-ch19.indd 575 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part III: Working with Data 576 Note With MX controls, you can leave out the <s:ArrayList> element and nest the data elements directly with the <mx:dataProvider>. This isn’t possible with Spark list controls, because the MXML compiler doesn’t know which implementing class of the IList interface to use. n Modifying data with the ArrayList API Because data is passed to the dataProvider as an ArrayList or ArrayCollection object, the class’s API can be used to access and manipulate the data. Even though the original data is hard-coded, the following ActionScript statement code would add a new item to the List object’s dataProvider when it contains simple String values: sizeList.dataProvider.addItem(‘Extra Large’); And this code would add a new item when it contains complex objects: stateList.dataProvider.addItem({state:’New York’,’Albany’}); The application in Listing 19.1 uses a List object with a hard-coded data provider and then enables the user to add data to the object with the addItem() method. LISTING 19.1 A List control with hard-coded data <?xml version=”1.0” encoding=”utf-8”?> <s:Application xmlns:fx=”http://ns.adobe.com/mxml/2009” xmlns:s=”library://ns.adobe.com/flex/spark” xmlns:mx=”library://ns.adobe.com/flex/mx”> <s:layout> <s:VerticalLayout horizontalAlign=”center” paddingTop=”20”/> </s:layout> <s:List id=”sizeList”> <s:dataProvider> <s:ArrayList> <fx:String>Small</fx:String> <fx:String>Medium</fx:String> <fx:String>Large</fx:String> </s:ArrayList> </s:dataProvider> </s:List> <s:HGroup> <s:Label text=”New Item:”/> <s:TextInput id=”itemInput”/> <s:Button label=”Add Item” click=”sizeList.dataProvider.addItem(itemInput.text)”/> </s:HGroup> </s:Application> 26_488959-ch19.indd 57626_488959-ch19.indd 576 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 19: Using List Controls 577 On the Web The code in Listing 19.1 is available in the Web site files as ListWithHardCodedData.mxml in the chapter19 project. n Declaring separate data objects with MXML tags You also can provide hard-coded data to a Spark list control from an <s:ArrayList> element declared within an <fx:Declarations> element or in ActionScript code. The application in Listing 19.2 declares an ArrayList and then provides the data to the List object through a binding expression. LISTING 19.2 A List control with data provided through a binding expression <?xml version=”1.0” encoding=”utf-8”?> <s:Application xmlns:fx=”http://ns.adobe.com/mxml/2009” xmlns:s=”library://ns.adobe.com/flex/spark” xmlns:mx=”library://ns.adobe.com/flex/mx”> <s:layout> <s:VerticalLayout horizontalAlign=”center” paddingTop=”20”/> </s:layout> <fx:Declarations> <s:ArrayList id=”myData”> <fx:String>Small</fx:String> <fx:String>Medium</fx:String> <fx:String>Large</fx:String> </s:ArrayList> </fx:Declarations> <s:List id=”sizeList” dataProvider=”{myData}”/> <s:HGroup> <s:Label text=”New Item:”/> <s:TextInput id=”itemInput”/> <s:Button label=”Add Item” click=”sizeList.dataProvider.addItem(itemInput.text)”/> </s:HGroup> </s:Application> On the Web The code in Listing 19.2 is available in the Web site files as ListWithBoundData.mxml in the chapter19 project. n Using dynamic data providers Data retrieved from an external source, such as the results of a remote server call through the Remote Procedure Call (RPC) components, or data retrieved from a local database (for an AIR desktop appli- cation) is typically stored in a data collection object. As described in Chapter 18, the data collection is typically declared in ActionScript code with the [Bindable] metadata tag or in MXML code. 26_488959-ch19.indd 57726_488959-ch19.indd 577 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part III: Working with Data 578 In ActionScript code, the declaration looks like this: import mx.collections.ArrayList; [Bindable] private var myData:ArrayList = new ArrayList(); And in MXML, it looks like this: <s:ArrayList id=”myData”/> Note Data objects that are declared in MXML are immediately instantiated and always bindable. n Regardless of how the data collection is declared, by making it bindable, you make it possible to pass the data to a List control with a simple binding expression: <s:List id=”sizeList” dataProvider=”{myData}”/> Using RPC components You can choose to retrieve data dynamically from many sources, including the Flex SDK compo- nents that are grouped together as the RPC classes. These classes are distinguished from each other by the data format they use to communicate with a remote server: l HTTPService. This class sends simple HTTP requests to URLs that return data format- ted as simple text or XML. For example, a call to an RSS feed from a blog or content-based Web site would be executed using the HTTPService class. l RemoteObject. This class sends and receives messages formatted in Action Message Format (AMF). This binary format is defined by Adobe and implemented in many of its server products, including LiveCycle Data Services, BlazeDS, and ColdFusion. l WebService. This class retrieves data from a server with calls formatted in the industry- standard SOAP format. These components and their methodologies are described starting in Chapter 23. All, however, are capable of returning data sets in the form of ArrayList or ArrayCollection objects that are suitable for use as List control data providers. Note The AMF data format was published by Adobe Systems in 2007 to support development of independent appli- cation server products that are compatible with Flex- and Flash-based applications. n Retrieving local data in AIR applications If you’re building an AIR-based desktop application, you can retrieve data from local XML files using the File and FileStream classes or from the local SQLite embedded database with classes such as SQLConnection and SQLStatement. These classes aren’t designed to return data in the ArrayList format directly; you typically need to manually wrap data into your data collection objects with explicit ActionScript code. 26_488959-ch19.indd 57826_488959-ch19.indd 578 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 19: Using List Controls 579 Controlling List Item Labels If a List control’s data provider contains simple values (such as String, Number, or Date), these values are displayed on each item by default. If the data provider contains complex objects (either instances of the ActionScript Object class or of your own custom value object classes), you can determine the text labels that are displayed in a List control’s items using one of these strategies: l The labelField property enables you to point to a specific named property of each object whose values should be displayed. l The labelFunction property enables you to customize each item’s label with your own ActionScript code. Using the labelField property Most List controls support the labelField property. This property enables you to indicate which of the named properties of data items in the control’s data provider is displayed at runtime. The default value of labelField is label. As a result, if the data provider’s objects have a prop- erty named label, that property’s value is displayed. In the following code, the ArrayList con- tains data objects with a label property. The List control displays the label property’s value on each of its items: <fx:Declarations> <s:ArrayList id=”stateData”> <fx:Object> <fx:label>CA</fx:label> <fx:capitol>Sacramento</fx:capitol> </fx:Object> <fx:Object> <fx:label>OR</fx:label> <fx:capitol>Salem</fx:capitol> </fx:Object> </s:ArrayList> </fx:Declarations> <s:List id=”stateList” dataProvider=”{stateData}”/> More commonly, the complex objects in the data collection have property names that are deter- mined by the structure of a database table, XML file, value object, or other existing data source. If you forget to set the labelField property on a List control that displays complex data objects, the control displays labels consisting of a set of [] characters wrapped around the word object and the object’s data type. If the data item is cast as an ActionScript Object, the result looks like this: [object Object] As shown in Figure 19.2, the results aren’t particularly useful, even when working with a value object class. 26_488959-ch19.indd 57926_488959-ch19.indd 579 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part III: Working with Data 580 FIGURE 19.2 A List control displaying a complex data object with no labelField setting To fix this behavior, you explicitly set the List control’s labelField to the name of the prop- erty you want to display: <fx:Declarations> <s:ArrayList id=”stateData”> <fx:Object> <fx:state>CA</fx:state> <fx:capitol>Sacramento</fx:capitol> </fx:Object> <fx:Object> <fx:state>OR</fx:state> <fx:capitol>Salem</fx:capitol> </fx:Object> </s:ArrayList> </fx:Declarations> <s:List id=”stateList” dataProvider=”{stateData}” labelField=”state”/> Figure 19.3 shows the same List control, this time displaying the value of the property named in the control’s labelField property. The application in Listing 19.3 uses the List control’s labelField property to determine which property value of each data object is displayed at runtime. LISTING 19.3 Using the labelField property <?xml version=”1.0” encoding=”utf-8”?> <s:Application xmlns:fx=”http://ns.adobe.com/mxml/2009” xmlns:s=”library://ns.adobe.com/flex/spark” 26_488959-ch19.indd 58026_488959-ch19.indd 580 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. [...]... pattern, they enable Flex Builder and the compiler to validate property names and provide code completion For example, when a user selects an item that represents a complex data object from a List control, you should first cast the control’s selectedItem property as the appropriate ActionScript class You can then refer to the object’s named properties and gain the benefit of Flex Builder s and the compiler’s... properties and events to determine their presentation and behavior l The list controls include the Spark List, DropDownList, ComboBox and ButtonBar, and the MX List, ComboBox, DataGrid, TileList, HorizontalList, Tree, AdvancedDataGrid, and OLAPDataGrid controls l MX list controls designed exclusively for use with AIR applications populate their data with information from the local client file system l You handle... based on the Spark ItemRenderer container and includes both the image and a Label control that displays the raw data 5 94 Chapter 19: Using List Controls LISTING 19.8 Using an inline renderer . multiple columns. 26 _48 8959-ch19.indd 5 742 6 _48 8959-ch19.indd 5 74 3/5/10 2:32 PM3/5/10 2:32 PM Please purchase PDF Split-Merge on www.verypdf.com to remove. unique events and properties designed for that control’s specific purpose and capabilities. 26 _48 8959-ch19.indd 5 842 6 _48 8959-ch19.indd 5 84 3/5/10 2:32