ListScrollStateHandler

#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);
                    }
                }
            }
        ]
    }
}

Since:

BlackBerry 10.0.0

Inheritance

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

QML properties

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

QML signals

onScrollingChanged	: {}
onAtBeginningChanged	: {}
onAtEndChanged	: {}
onFirstVisibleItemChanged	: {}
onCreationCompleted	: {}
onObjectNameChanged	: {}

Properties Index

bool	scrolling [read-only]
bool	atBeginning [read-only]
bool	atEnd [read-only]
QVariantList	firstVisibleItem [read-only]
QString	objectName
QObject	parent [read-only]

Public Functions Index

	ListScrollStateHandler (ListView *target=NULL)
virtual	~ListScrollStateHandler ()
bool	isScrolling () const
bool	isAtBeginning () const
bool	isAtEnd () const
QVariantList	firstVisibleItem () const
void	setObjectName (const QString &name)
virtual Q_INVOKABLE QString	toDebugString () const

Static Public Functions Index

Builder

create (ListView *target)

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)

Signals Index

void	scrollingChanged (bool scrolling)
void	atBeginningChanged (bool atBeginning)
void	atEndChanged (bool atEnd)
void	firstVisibleItemChanged (QVariantList firstVisibleItem)
void	creationCompleted ()
void	objectNameChanged (const QString &objectName)

Properties

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

bool atBeginning[read-only]

A read-only property that indicates whether the list is positioned at the start 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

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

QString objectName

This property is overridden from QObject.

As the objectName property is overridden from the QObject class, this signal will not be emitted if setObjectName() function is called directly on QObject.

The default value of this property is QString::null.

See:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parent[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 (
ListView *target)

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

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

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

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

void setObjectName (
const QString &name)

Sets the objectName property.

Parameters
name	The new name for the object.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Static Public Functions

Builder create (
ListView *target)

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 (
QObject *parent)

Constructs an instance of BaseObject's subclass.

Parameters
parent	An optional parent, defaults to 0.

Since:

BlackBerry 10.0.0

Signals

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 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 (
QVariantListfirstVisibleItem)

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 creationCompleted ()

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node, or when an object is being constructed using its builder class.

This signal is emitted only 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 is emitted to indicate 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:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (
const QString &objectName)

This signal is emitted when the objectName property is changed.

See:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0

ListScrollStateHandler

Inheritance

QML properties

QML signals

Properties Index

Public Functions Index

Static Public Functions Index

Protected Functions Index

Signals Index

Properties

bool scrolling[read-only]

bool atBeginning[read-only]

bool atEnd[read-only]

QVariantList firstVisibleItem[read-only]

QString objectName

QObject parent[read-only]

Public Functions

ListScrollStateHandler (ListView *target)

virtual~ListScrollStateHandler ()

bool isScrolling ()

bool isAtBeginning ()

bool isAtEnd ()

QVariantList firstVisibleItem ()

void setObjectName (const QString &name)

virtual Q_INVOKABLE QString toDebugString ()

Static Public Functions

Builder create (ListView *target)

Protected Functions

BaseObject (QObject *parent)

Signals

void scrollingChanged (boolscrolling)

void atBeginningChanged (boolatBeginning)

void atEndChanged (boolatEnd)

void firstVisibleItemChanged (QVariantListfirstVisibleItem)

void creationCompleted ()

void objectNameChanged (const QString &objectName)

ListScrollStateHandler (
ListView *target)

void setObjectName (
const QString &name)

Builder create (
ListView *target)

BaseObject (
QObject *parent)

void scrollingChanged (
boolscrolling)

void atBeginningChanged (
boolatBeginning)

void atEndChanged (
boolatEnd)

void firstVisibleItemChanged (
QVariantListfirstVisibleItem)

void objectNameChanged (
const QString &objectName)