AppListView

A ListView providing a native ScrollIndicator, an empty view and swipe gestures for its list delegates More...

Import Statement: import VPlayApps 1.0
Inherits:

ListView

Properties

Methods

Detailed Description

AppListView is an extension of the basic QML ListView with functionality for the V-Play AppSDK.

It adds capability for displaying a view when the list is empty, and for using SwipeOptionsContainer as ListView::delegate.

To use predefined components for often used list features, use a PullToRefreshHandler and/or VisibilityRefreshHandler together with the AppListView.

Thus we recommend using AppListView instead of ListView in your whole project.

Usage Examples

Simple AppListView

The easiest way to to use the AppListView is by choosing the SimpleRow type as the ListView::delegate. If the model is an array, the SimpleRow properties are automatically initialized with the matching array properties.

Note: If no specific width and height is set, the AppListView uses the parent's width and height by default.

 AppListView {
   delegate: SimpleRow {}
   model: [
     { text: "Widget test",
       detailText: "Some of the widgets available in V-Play AppSDK",
       icon: IconType.tablet },
     { text: "Shown are:",
       detailText: "ListPage, NavigationBar with different items, Switch",
       icon: IconType.question }
   ]
 }

Using a model based on the ListModel type is also possible:

 AppListView {
   model: ListModel {
     ListElement { name: "Banana" }
     ListElement { name: "Apple" }
     ListElement { name: "Potato" }
   }
   delegate: SimpleRow { text: name }
 }

AppListView with Sections

Similar to the QML ListView type, sections are created by specifying a ListView::section.property and ListView::section.delegate. Just use the SimpleSection type as the delegate to get a default section look that matches the underlying platform style.

 AppListView {
   model: ListModel {
     ListElement { type: "Fruits"; name: "Banana" }
     ListElement { type: "Fruits"; name: "Apple" }
     ListElement { type: "Vegetables"; name: "Potato" }
   }
   delegate: SimpleRow { text: name }

   section.property: "type"
   section.delegate: SimpleSection { }
 }

Note: Sections are only available if the ListView::model is based on the ListModel type. To create sections for an array model, use the AppListView::prepareArraySections function.

Property Documentation

backgroundColor : color

The background color of the list view. By default the color matches Theme::secondaryBackgroundColor on iOS and is transparent on all other platforms.

This QML property was introduced in V-Play 2.7.0.


emptyText : AppText

An Apptext that is visible when the AppListView contains no elements.

To display a text, change the Text::text property of emptyText:

 AppListView {
   model: [] // no elements

   emptyText.text: "No items available"
 }

emptyView : Item

A container that is visible when the AppListView contains no elements.

This container contains one AppText per default, accessible via emptyText property.

To add custom content, change the Item::children property of emptyView:

 AppListView {
   model: [] // no elements

   emptyView.children: [ CustomEmptyView {} ]
 }

scrollIndicatorVisible : bool

Whether a ScrollIndicator should be visible when the user scrolls through the list or not.


scrollsToTop : bool

By default, an AppListView component scrolls to the top of the list if a user taps the status bar on iOS. Set this property to false to disable that behavior.


Method Documentation

getScrollPosition()

Returns an object containing internal information about the current scroll position of the list.

This object can later be passed to restoreScrollPosition() to restore this exact position in the list.

This is useful, when the list's model gets updated with new items, to preserve the scroll position. Otherwise, the list jumps to the top when the model changes.

Example code:

 AppListView {
   model: myModel

   function update() {
     var pos = getScrollPosition() //retrieve scroll position data
     loadMoreItems()         //adds new items to list model
     restoreScrollPosition(pos) //scrolls to the previous position
   }
 }

prepareArraySections(data)

Currently, only models of type ListModel support the ListView::section features. This function is a convenience function that allows sections for array models too.

Example code:

 AppListView {
   delegate: SimpleRow { }
   model: prepareArraySections(myArrayModel)

   section.property: "category"
   section.delegate: SimpleSection { }
 }

This QML method was introduced in V-Play 2.6.2.


restoreScrollPosition(data, numNewItemsOnTop)

Restores a previous scroll position retrieved with getScrollPosition().

If items have been added to the list's model on the top, the number of added items should be passed as the second parameter. If items have been added on the bottom, this parameter can be left out.

This is useful, when the list's model gets updated with new items, to preserve the scroll position. Otherwise, the list jumps to the top when the model changes.

Example code:

 AppListView {
   model: myModel

   function update() {
     var pos = getScrollPosition() //retrieve scroll position data
     loadMoreItems()         //adds new items to list model
     restoreScrollPosition(pos) //scrolls to the previous position
   }
 }

Videos

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