List view

A list view determines how the data in your list is displayed in your app. Your list items might be as simple as text entries, or as complex as custom QML components with several UI controls defined within them. You can create a list view in either QML or C++.


Screens showing a list view with a basic appearance and a list view with a customized appearance.

A list view must have a data model associated with it to display any items in the list. The list view itself doesn't hold any list data; it just provides a visual template for the appearance of the list. For more information about data models in Cascades, see Data models.

Creating a list view in QML

You can use a  ListView to create a list in QML. This control includes properties such as the data model to use for the list, how many items can be selected at once, and whether a scroll bar is displayed when the list scrolls.

The following code sample demonstrates how to create a simple list in QML. The code sample uses an .xml file called items.xml to define the data model for the list. This approach is the one of the easiest ways to populate a list with data, and lets you create lists entirely in QML (instead of a combination of QML and C++). It's also easier to demonstrate the features of ListView without worrying about the specifics of the data model, so this approach is used throughout this section. For more information about the format of this .xml file, as well as other data models that you can use, see Data models.

If you want to run these code samples yourself, download the items.xml file. This file starts with the basic data that you see in the example below. Feel free to add more data entries or property names and see how the displayed list changes.

import bb.cascades 1.0
 
Page {
    content: Container {
        ListView {
            dataModel: XmlDataModel {
                source: "models/items.xml"
            }
        }
    }
}

In Cascades, all content for a screen must be added to a root element that inherits from the AbstractPane class. In the example above, the Page class is used as the root element. For simplicity, subsequent code samples omit the Page element.

The code sample above creates the type of list that you see to the right. Each list item has a type that you can define, and you can use the type to determine what the item looks like in the list. For example, you could use a type of "header" or "headerItem" for headings in the list, and you could use a type of "item" or "listItem" for normal items. You define item types when you create your data model. In the code sample above, the item types are defined in the items.xml file, along with the data for each item.

By default, a ListView provides two styles for list items. For items with the "header" type (the "Fruit" and "Vegetables" items in the example to the right), the list uses a  Header. This style uses a distinct background, and you can use it to separate or group items in the list. For items with any other type ("Oranges", "Broccoli", and other items), the list uses a StandardListItem.

Screen showing a list with two headers and six list items.

Customizing the appearance of list items

You can create your own styles for list items instead of using the default styles. You can use the listItemComponents list, which is part of  ListView, to specify the appearance of each type of list item.

The listItemComponents list is available only in QML, and accepts a list of  ListItemComponent objects. Each object is associated with a type of list item, and represents the visual appearance of that type. Inside a ListItemComponent, you can use UI controls (such as  Container Label, ImageView, and so on) to create the look that you want. You can even use custom QML components that you create yourself. The ListItemComponent is then used as a template for the specified item type in the list.

You specify the type that a ListItemComponent applies to by using the type property. For example, you could specify different types for header items, first-level list items, and second-level list items.

Here's how to create a list that uses a custom appearance for its items. The item types "header" and "listItem" are defined in the items.xml file, along with the data for the list. The "header" type uses a ListItemComponent with a single Label, which contains properties that define the appearance of the type, such as font and text color. The "listItem" type uses a ListItemComponent with a  CheckBox and a Label.

Screen showing a list view with a customized appearance.
import bb.cascades 1.0
 
Page {
    content: Container {    
        // Create a ListView that uses an XML data model
        ListView {
            dataModel: XmlDataModel {
                source: "models/items.xml"
            }
         
            // Add appearance definitions for the list items using the
            // listItemComponents list
            listItemComponents: [
         
                // The first ListItemComponent defines how "header" items
                // should appear. These items use a Label.
                ListItemComponent {
                    type: "header"
                    Label {
                        text: ListItemData.title
                     
                        // Apply a text style to create a large, bold font with
                        // a specific color
                        textStyle {
                            base: SystemDefaults.TextStyles.BigText
                            fontWeight: FontWeight.Bold
                            color: Color.create ("#7a184a")
                        }
                    }
                },
             
                // The second ListItemComponent defines how "listItem" items
                // should appear. These items use a Container that includes a
                // CheckBox and a Label.
                ListItemComponent {
                    type: "listItem"
                    Container {
                        layout: StackLayout {
                            orientation: LayoutOrientation.LeftToRight
                        }
                        CheckBox {
                            // Determine whether the CheckBox should be checked
                            // according to a value in the data model
                            checked: ListItemData.checked
                        }
                        Label {
                            text: ListItemData.title
                         
                            // Apply a text style to create a title-sized font
                            // with normal weight
                            textStyle {
                                base: SystemDefaults.TextStyles.TitleText
                                fontWeight: FontWeight.Normal
                            }
                        }
                    } // end of Container
                } // end of second ListItemComponent
            ] // end of listItemComponents list
        } // end of ListView
    } // end of Container
} // end of Page

If you want to use the default styles that are provided by Header and StandardListItem, but you need a bit more flexibility with the data that's displayed, you can use these controls inside their own ListItemComponent objects. Both Header and StandardListItem include additional properties that you can use to add more information to list items. For example, StandardListItem lets you add an image and subtitle text to each list item.

When you add images to list items, you should add the images asynchronously instead of as assets in your project. If you add the images as assets, the ListView might have to wait to load the images before displaying the list items, which can adversely affect the scrolling performance of the list. To learn more about loading images, see Images.

Here's how to create a list that uses both Header and StandardListItem inside their own ListItemComponent objects. Each Header includes both a title and a subtitle. The subtitle appears to the right of the title. Each StandardListItem includes a title, a short description, and a status. The short description appears below the title, and the status appears to the right of the title.

Screen showing a list view with subtitles and short descriptions.
import bb.cascades 1.0
 
Page {
    content: Container {
        // Create a ListView that uses an XML data model
        ListView {
            dataModel: XmlDataModel {
                source: "models/items.xml"
            }
 
            listItemComponents: [
                ListItemComponent {
                    type: "header"
 
                    // Use a predefined Header to represent "header"
                    // items
                    Header {
                        title: ListItemData.title
                        subtitle: ListItemData.subtitle
                    }
                },
                ListItemComponent {
                    type: "listItem"
 
                    // Use a predefined StandardListItem to represent "listItem"
                    // items
                    StandardListItem {
                        title: ListItemData.title
                        description: ListItemData.subtitle
                        status: ListItemData.status
                    }
                } // end of second ListItemComponent
            ] // end of listItemComponents list
        } // end of ListView
    } // end of Container
} // end of Page

Accessing properties in a data model

When you use  ListItemComponent objects for your list items, the data for each item isn't populated automatically from the data model. You need to extract the relevant data for each item from the data model and create your ListItemComponent objects based on this data.

Fortunately,  ListView provides an easy way to access properties in the data model. The ListItemData property represents the data model for the ListView, and you can access specific item properties in the model just as you would access the properties of any QML component. For example, if the items in your data model included a name property, then you could access it in a ListItemComponent by using ListItemData.name.

In the code samples in the previous section, a property called title was accessed from the data model and used to set the text for the  Label StandardListItem, and  Header controls. This property is part of the data model and is specified for each list item in the model. Properties called checked,subtitle, and status were also accessed.

There are other properties of list items that you can access, which are provided by the ListView, instead of the data model. These properties are available regardless of what properties the data model contains. You can access these properties by using the prefix ListItem. Some of these properties include:

  • ListItem.active - Indicates whether the list item is active. An item is active if the user is holding a finger on it.
  • ListItem.selected - Indicates whether the list item is selected. An item is selected if the user tapped the item and it appears selected on the screen.
  • ListItem.data - Provides access to the list item's data in the data model. This is equivalent to the ListItemData property that's used above.

For a complete list of properties, see the API reference for ListView.

Last modified: 2013-12-21

comments powered by Disqus