API Documentation

Documentation for developing SailfishOS applications

ColumnView QML Type

Repeatedly instantiates a delegate in a column More...

Import Statement: import Sailfish.Silica 1.0

Properties

Detailed Description

ColumnView provides a Column-like model view that only instantiates delegates as required.

It is functionally equivalent to the QtQuick Repeater element used inside a Column, using a model to repeatedly instantiate a delegate. The ColumnView, however, only instantiates delegates as they are required for presentation, rather than instantiating all delegates on creation. The ColumnView has the same appearance and behaviour as the Column/Repeater combination, but delays the cost of creation until delegates are displayed, and is thus more appropriate for lists that extend beyond a single screen.

It is useful when a flickable view is composed of multiple Column-type layouts, and:

  • It is not necessary to scroll each layout independently of the parent flickable
  • Each layout may contain a large amount of content, or the delegates have complex details that take time to render, and so we would prefer not to unnecessarily render the delegates which are not immediately visible

This targets a limited number of use cases, so generally a SilicaListView or Column/Repeater combination can be used instead of a ColumnView.

Below is an example which does benefit from using ColumnView rather than SilicaListView. Here, the SilicaFlickable contains multiple ColumnView children, whose models will have 100 items each when the Button is pressed to generate the model content. However, the ColumnView will only create and render delegate instances that are currently shown on-screen (or are within the cacheBuffer), which greatly enhances performance:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 ApplicationWindow {
     initialPage: Component {

         Page {
             SilicaFlickable {
                 anchors.fill: parent
                 contentHeight: mainColumn.height

                 Column {
                     id: mainColumn
                     width: parent.width

                     PageHeader {}

                     Button {
                         text: "Show search results"
                         anchors.horizontalCenter: parent.horizontalCenter
                         onClicked: {
                             console.log("Generating content...")
                             firstColumn.model = 100
                             secondColumn.model = 100
                             console.log("Done!")
                         }
                     }

                     SectionHeader { text: "Search results" }

                     ColumnView {
                         id: firstColumn
                         width: parent.width
                         itemHeight: Theme.itemSizeSmall

                         delegate: BackgroundItem {
                             width: parent.width
                             Label {
                                 text: "Search result " + model.index
                                 anchors.centerIn: parent
                             }
                         }
                     }

                     SectionHeader { text: "You might also like..."}

                     ColumnView {
                         id: secondColumn
                         width: parent.width
                         itemHeight: Theme.itemSizeSmall

                         delegate: BackgroundItem {
                             width: parent.width
                             Label {
                                 text: "Suggestion " + model.index
                                 anchors.centerIn: parent
                             }
                         }
                     }
                 }
             }
         }
     }
 }

(Notice that the itemHeight must be set to the default height of each instantiated delegate.)

If the content was shown with a Column/Repeater combination rather than a ColumnView, the view would take much longer to render as all of the view delegate instances would be created even if they are not in view. Also, the ColumnViews cannot be replaced with non-interactive SilicaListViews; this would require the list view height to be set to its contentHeight so that the parent flickable can be scrolled all the way from the top of the first view to the bottom of the second view, but this would cause all of the view's delegate instances to be created unnecessarily when out of view, and thus result in the same problem.

If there was only one column-type view rather than two, then a SilicaListView could be used instead, with the PageHeader and Button moved into the header of the list view.

Property Documentation

cacheBuffer : int

The maximum number of pixels to be cached outside the visible area in pre-generated delegate items.

See also cacheBuffer.


[read-only] count : int

This property holds the number of items in the ColumnView's model.


delegate : Component

The delegate provides the template for each item instantiated by the ColumnView.


itemHeight : real

The default height of the items to be instantiated by the ColumnView. This value is required to calculate the content height of the column.


maximumVisibleHeight : real

The maximum height of the column which will be visible at any given time. The default value is Screen.height.


model : var

The model provides the list of items to be instantiated by the ColumnView.


We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.