Customize Your List Items, Now With Out-Of-The-Box Highlighting Behavior!

Native SDK Development

The BlackBerry 10.2 SDK comes with new APIs that give you many more customization options. In a previous blog post, I shed light on the new FontFaceRule API that allows you to use custom fonts. In this blog post, I will focus on the much awaited CustomListItem API.

Up until the release of the 10.2 SDK, you had two options to define list items (ListItemComponent) of your list views (ListView).

The StandardListItem API, which as the name suggests, is a basic template for displaying list items in a standard way with a title, description, status and image.

ListItemComponent {                   
    type: "item1"
    StandardListItem {
        title: ListItemData.text
        description: ListItemData.description
        status: ListItemData.status
        imageSource: "images/" + ListItemData.image
        contextActions: [
            ActionSet {
            }
        ]
     }
}

CustomListItem_1

Or, if the design of your app requires any customization to the list items beyond what is available by the StandardListItem, through defining the UI controls and their layout directly inside the ListItemComponent.

ListItemComponent {
    type: "item2"
    Container {
        id: itemRoot                 
        layout: DockLayout {
        }                       
        Container {
            layout: StackLayout {
                orientation: LayoutOrientation.LeftToRight
            }
            verticalAlignment: VerticalAlignment.Fill
            rightPadding: 20
            ImageView {
                id: iconImage
                verticalAlignment: VerticalAlignment.Center
                imageSource: "images/" + ListItemData.image
                minHeight: 120
                minWidth: 120
                maxHeight: 120
                maxWidth: 120
            }
            Container {
                verticalAlignment: VerticalAlignment.Center
                leftPadding: 20
                Container {
                    layout: StackLayout {
                        orientation: LayoutOrientation.LeftToRight
                    }
                    Label {
                        layoutProperties: StackLayoutProperties {
                            spaceQuota: 1
                        }
                        id: titleLabel
                        text: ListItemData.text
                        textStyle.fontSize: FontSize.XLarge
                    }
                    Label {
                        id: statusLabel
                        text: ListItemData.status
                        verticalAlignment: VerticalAlignment.Bottom
                        textStyle.textAlign: TextAlign.Right
                        textStyle.fontSize: FontSize.XSmall
                    }
                }
                Label {
                    id: descriptionLabel
                    text: ListItemData.description
                    topMargin: 0
                    bottomMargin: 0
                    textStyle.fontSize: FontSize.Medium
                }
            }
        }
        contextActions: [
            ActionSet {
            }
        ]
    }
}

CustomListItem_2

Figure a – No highlighting (code provided above)

CustomListItem_3

Figure b – Highlighting implemented (code not shown)

Even though the StandardListItem doesn’t allow for a lot of visual customization, it provides a smooth built-in highlight behavior on user selection or long-press that gives you a nice effortless user interaction edge that follows the BlackBerry 10 UI guidelines on highlight behavior. For custom list items, however, you have to implement this charming highlight behavior yourself with a few extra lines of code.

To provide further consistency to the BlackBerry 10 user experience and simplify your code, we are introducing the CustomListItem API with the release of 10.2 SDK.

The API is an “empty template” that allows you to customize the visuals of your list items through the simple single-line property setting approach you are used to in QML. You can now:

  • Specify the visual controls and visual layout of your list items under the content property.
  • Specify the list item highlighting behavior on user select and long-press using the highlightAppearance property. You can set the HighlightAppearance to None, Frame or Full.
  • Show/hide a divider using the dividerVisible property to give visual separation between list items.
ListItemComponent {
    type: "item3"
    CustomListItem {
        dividerVisible: true //or false                      
        highlightAppearance: HighlightAppearance.Full //Frame,None                      
        content: [
        …
        ]
    }
}

CustomListItem_4

 
ListItemComponent {
    type: "item3"
    CustomListItem {
        dividerVisible: true //or false                      
        highlightAppearance: HighlightAppearance.Frame                      
        content: [
        
        ]
    }
}

CustomListItem_5

ListItemComponent {
    type: "item3"
    CustomListItem {
        dividerVisible: true //or false                      
        highlightAppearance: HighlightAppearance.None                      
        content: [
        
        ]
    }
}

CustomListItem_6

If you had to implement your own selection highlighting logic for your custom list items before, then you too will definitely see this API as a welcome addition to our set of native API’s.

I encourage you to try it out. It’s easy to use and well-documented. And above all, it allows you to give the BlackBerry 10 user the same look and feel they have come to expect from using the BlackBerry 10 core applications.

Let me know if you have any questions or comments in the comments’ section below or on @SamarAbdelsayed. I will be happy to answer them for you!

About Samar

A member of the awesome Developer Relations group at BlackBerry. A passionate flow charter and C++ coder. In love with Cascades. It is very easy to learn and truly fun to work with.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus