ListScrollStateHandler

Since: BlackBerry 10.0.0

#include <bb/cascades/ListScrollStateHandler>

Listens for scroll state changes on a ListView.

The properties in this class provide read-only access to the scroll state of the target ListView.

The properties are changed asynchronously when the scroll state of the target ListView changes. Because of this, the state reported by a ListScrollStateHandler may be out of sync for a few frames after creation, or when the state changes.

The target ListView can only be specified during construction using the constructor, builder, or as a parent component in QML. The state handler cannot be changed at run time.

Here's an example of how to track the ListView scroll state in C++.

ListView *pListView = ListView::create();

ListScrollStateHandler::create(pListView)
    .onScrollingChanged(this, SLOT(handleScrollingChanged(bool)));

// pListView owns the created handler so there is no need to keep a reference
// to it, and it will be deleted when the ListView is deleted.
In QML, the handler must be attached to a ListView. The following sample demonstrates how to show a Label when a ListView is scrolling.
Container {
    Label {
        id: scrollLabel
        text: "Scrolling"
        opacity: 0
    }

    // The ListView we want to track.
    // Note that this ListView lacks a DataModel. See the ListView
    // documentation for a complete ListView example.
    ListView {
        attachedObjects: [
            // This handler is tracking the scroll state of the ListView.
            ListScrollStateHandler {
            id: scrollStateHandler

                onScrollingChanged: {
                    if (scrolling) {
                        scrollLabel.setOpacity(1);
                    }
                    else {
                        scrollLabel.setOpacity(0);
                    }
                }
            }
        ]
    }
}


Overview

Inheritance

bb::cascades::BaseObject
bb::cascades::ListScrollStateHandler

QML properties

atBeginning: bool [read-only]
atEnd: bool [read-only]
firstVisibleItem: QVariantList [read-only]
scrolling: bool [read-only]
objectName: QStringInherited
parent: QObject [read-only]Inherited

Properties Index

boolatBeginning [read-only]
boolatEnd [read-only]
QVariantListfirstVisibleItem [read-only]
boolscrolling [read-only]
QStringobjectNameInherited
QObjectparent [read-only]Inherited

Public Functions Index

ListScrollStateHandler (ListView *target=NULL)
virtual ~ListScrollStateHandler ()
QVariantListfirstVisibleItem () const
boolisAtBeginning () const
boolisAtEnd () const
boolisScrolling () const
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Static Public Functions Index

Buildercreate (ListView *target)

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voidatBeginningChanged (bool atBeginning)
voidatEndChanged (bool atEnd)
voidfirstVisibleItemChanged (QVariantList firstVisibleItem)
voidscrollingChanged (bool scrolling)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

bool atBeginning[read-only]

A read-only property that indicates whether the list is positioned at the start of its items.

Since:

BlackBerry 10.0.0

bool atEnd[read-only]

A read-only property that indicates if the list is positioned at the end of its items.

This property changes when the scroll position of the target ListView changes.

The default value of this property is false.

Since:

BlackBerry 10.0.0

QVariantList firstVisibleItem[read-only]

A read-only property that holds the index path to the first visible item.

This property changes when the first visible item of the target ListView changes. When there are no items in the list, this property holds an empty QVariantList.

The default value of this property is an empty QVariantList.

Since:

BlackBerry 10.0.0

bool scrolling[read-only]

A read-only property representing the scroll state of the target ListView.

This property changes when the scroll state of the target ListView changes. A scrollingChanged(bool) signal is emitted whenever the property changes.

The default value of this property is false.

Since:

BlackBerry 10.0.0

QString objectNameInherited

This property is overridden from QObject.

See also:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parentInherited[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

Public Functions

ListScrollStateHandler (

Constructs a ListScrollStateHandler with a specified ListView as the target node.

The constructed handler will receive scroll state changes from the ListView and emit a scrollingChanged() signal.

The passed ListView will assume ownership of this instance of ListScrollStateHandler.

Parameters
target

The target ListView for this handler.

Since:

BlackBerry 10.0.0

virtual~ListScrollStateHandler ()

Destructor.

Since:

BlackBerry 10.0.0

QVariantList firstVisibleItem ()

Returns the first visible item in the target ListView.

Return:

The first visible item in the target ListView, or an empty QVariantList if the ListView is empty.

Since:

BlackBerry 10.0.0

bool isAtBeginning ()

Checks if the target ListView is at its start position.

Return:

true if the target ListView is positioned at the start of its list items, false otherwise.

Since:

BlackBerry 10.0.0

bool isAtEnd ()

Checks if the target ListView is at its end position.

Return:

true if the target ListView is positioned at the end of its list items, false otherwise.

Since:

BlackBerry 10.0.0

bool isScrolling ()

Returns the current scroll state of the target ListView.

Return:

true if the target ListView is currently scrolling, false otherwise.

Since:

BlackBerry 10.0.0

void setObjectName (Inherited

Sets the objectName property.

Parameters
name

The new name for the object.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()Inherited

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Static Public Functions

Builder create (

Constructs a builder for a ListScrollStateHandler with a specified ListView as the target node.

The constructed handler will receive calls when the scroll state of the ListView changes and emit the scrollingChanged() signal.

The passed ListView will assume ownership of this instance of ListScrollStateHandler.

ListScrollStateHandler::create(pListView)
    .onScrollingChanged(pMyObject, SLOT(onScrollingChanged(bool)));
Parameters
target

A non-null ListView that will be used as a target for this handler.

Since:

BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (Inherited

Constructs an instance of BaseObject's subclass.

Parameters
parent

An optional parent, defaults to 0.

Since:

BlackBerry 10.0.0

Signals

void atBeginningChanged (
  • boolatBeginning)

Emitted when the target ListView scrolls to, or away from, its beginning position.

Parameters
atBeginning

true if the target ListView is at the beginning position, false otherwise.

Since:

BlackBerry 10.0.0

void atEndChanged (
  • boolatEnd)

Emitted when the target ListView scrolls to, or away from, its end position.

Parameters
atEnd

true if the target ListView is at the end position, false otherwise.

Since:

BlackBerry 10.0.0

void firstVisibleItemChanged (

Emitted when the first visible item of the target ListView changes.

Parameters
firstVisibleItem

The index path to the first visible item of the target ListView, or an empty QVariantList if there are no items in the ListView.

Since:

BlackBerry 10.0.0

void scrollingChanged (
  • boolscrolling)

Emitted when the target ListView starts or stops scrolling.

Parameters
scrolling

true when the target ListView starts scrolling, false when the target ListView stops scrolling.

Since:

BlackBerry 10.0.0

void creationCompleted ()Inherited

Emitted when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class.

This signal indicates that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See also:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-29



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus