ListPage

A Page item with an AppListView as a single child. More...

Import Statement: import VPlayApps 1.0
Inherits:

Page

Properties

Signals

Detailed Description

The ListPage component is a convenience item wrapping a single AppListView component into a Page object. It also contains a PullToRefreshHandler, which can be activated by setting pullToRefreshHandler.pullToRefreshEnabled. It is disabled by default in a ListPage.

A lot of app screens consist just of a single AppListView, therefore this component can save some boilerplate code.

The contained listView comes pre-initialized with a delegate of type SimpleRow. If the section features are used, the SimpleSection type is used as the default section delegate.

Example Usage

The easiest way to create a list is to use the ListPage type. It internally uses an AppListView with a SimpleRow delegate for the list rows:

iOS Android

 import VPlayApps 1.0

 App {
  NavigationStack {
    ListPage {
      title: "Basic List Example"
      model: [
        {
          text: "Apple",
          detailText: "A delicious fruit with round shape",
          icon: IconType.apple
        },
        {
          text: "Beer",
          detailText: "A delicous drink",
          icon: IconType.beer
        }
      ]
    }
  }
 }

The model-delegate system also supports JSON data structures for your data model. This makes it easy to work with and display data from REST APIs.

More ListView Examples

See the guide Use ScrollViews and ListViews in Your App for many more list view examples, for example how to customize the look of your list item delegates.

How do I know which list item is clicked on?

The ListPage::itemSelected signal allows to handle click events on a list cell. This signal only fires when using the default SimpleRow delegate. For custom delegate items, you can add your own MouseArea for handling touch input.

 import VPlayApps 1.0

 App {
  NavigationStack {
    ListPage {
      title: "Clickable List Example"

      onItemSelected: console.log("Clicked Item #"+index+": "+JSON.stringify(item))

      model: [
        {
          text: "Apple",
          detailText: "A delicious fruit with round shape",
          icon: IconType.apple
        },
        {
          text: "Beer",
          detailText: "A delicous drink",
          icon: IconType.beer
        }
      ]
    }
  }
 }

How do I update ListViews dynamically?

The internal list view of the page updates its UI automatically whenever the model changes - at least when you describe your model as a ListModel type.

For plain JSON-based models, the list is not notified when some data values within the JSON structure change. In this case, you can manually trigger a property-changed signal, which in turn updates the UI of the list:

 import VPlayApps 1.0

 App {
  NavigationStack {
    ListPage {
      id: page
      title: "Append List Item Example"

      property var listData: [
        {
          text: "Apple",
          detailText: "A delicious fruit with round shape",
          icon: IconType.apple
        },

        {
          text: "Beer",
          detailText: "A delicous drink",
          icon: IconType.beer
        }
      ]

      model: listData
      onItemSelected: {
        page.listData.push(item) // add copy of clicked element at end of model
        page.listDataChanged() // signal change of data to update the list
      }
    }
  }
 }

More Frequently Asked Development Questions

Find more examples for frequently asked development questions and important concepts in the following guides:

Property Documentation

compactSections : bool

When the section feature is used, this property allows to switch the style of the SimpleSection type that is used as the ListView::section.delegate by default. It sets the initial value of the SimpleSection::style.compactStyle property.

This QML property was introduced in V-Play 2.6.2.


delegate : alias

An alias to access and set the ListView::delegate data.


emptyText : alias

An alias to access and set the AppListView::emptyText data.


emptyView : alias

An alias to access and set the AppListView::emptyView data.


listView : alias

An alias to access the component's AppListView child.


model : var

The model to be used for the ListView::model data.


pullToRefreshHandler : alias

An alias to a PullToRefreshHandler item inside the AppListView.

Activate it by setting pullToRefreshEnabled to true and connecting the refresh signal.


pullToRefreshHandler. : PullToRefreshHandler

An alias to a PullToRefreshHandler item inside the AppListView.

Activate it by setting pullToRefreshEnabled to true and connecting the refresh signal.


section : alias

An alias to access and set the ListView::section configuration to display a ListView with sections. The ListPage uses the SimpleSection type as the ListView::section.delegate by default.

Note: Usually, only a model based on the ListModel type supports sections. ListPage automatically uses the AppListView::prepareArraySections function to allow sections also for arrays.

Example code:

 ListPage {
   model: [{ type: "Fruits", text: "Banana" },
     { type: "Fruits", text: "Apple" },
     { type: "Vegetables", text: "Potato" }]
   section.property: "type"
 }

This QML property was introduced in V-Play 2.6.2.


Signal Documentation

itemSelected(int = index, var = item)

This convenience handler gets called when a row within the contained listView was selected.

Note: This is only called if the delegate is not overridden by a custom delegate.


Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support