diff options
| author | Mitch Curtis <mitch.curtis@qt.io> | 2024-11-19 10:33:58 +0800 |
|---|---|---|
| committer | Mitch Curtis <mitch.curtis@qt.io> | 2024-11-28 16:40:47 +0800 |
| commit | 473fc5005e2811347f00679e56e90ec0915f8041 (patch) | |
| tree | 24b6b1e16872e6873f8a8574339bd0cf44528b27 /src/quick/items/qquicklistview.cpp | |
| parent | 433a330dfb6bf75bf475fac25be287c18e18427e (diff) | |
Doc: add "Avoid Storing State in Delegates" section to ListView's docs
This is mentioned in a couple of places, so add a dedicated section
and link to it.
Also add a section to the Qt Quick best practices page.
Pick-to: 6.5 6.8
Change-Id: I0ba528e6c37b0c9c82ca1847817251f176b7f978
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
Diffstat (limited to 'src/quick/items/qquicklistview.cpp')
| -rw-r--r-- | src/quick/items/qquicklistview.cpp | 24 |
1 files changed, 21 insertions, 3 deletions
diff --git a/src/quick/items/qquicklistview.cpp b/src/quick/items/qquicklistview.cpp index 54b1157881..18a9495005 100644 --- a/src/quick/items/qquicklistview.cpp +++ b/src/quick/items/qquicklistview.cpp @@ -2086,7 +2086,7 @@ QQuickItemViewAttached *QQuickListViewPrivate::getAttachedObject(const QObject * The list view itself is a focus scope (see \l{Keyboard Focus in Qt Quick} for more details). Delegates are instantiated as needed and may be destroyed at any time. - As such, state should \e never be stored in a delegate. + As such, \l {Avoid Storing State in Delegates}{state should \e never be stored in a delegate}. Delegates are usually parented to ListView's \l {Flickable::contentItem}{contentItem}, but typically depending on whether it's visible in the view or not, the \e parent can change, and sometimes be \c null. Because of that, binding to @@ -2224,8 +2224,9 @@ QQuickItemViewAttached *QQuickListViewPrivate::getAttachedObject(const QObject * item is reused. This includes \c index and \c row, but also any model roles. - \note Avoid storing any state inside a delegate. If you do, reset it - manually on receiving the \l ListView::reused signal. + \note \l {Avoid Storing State in Delegates}{Avoid storing any state inside + a delegate}. If you do, reset it manually on receiving the + \l ListView::reused signal. If an item has timers or animations, consider pausing them on receiving the \l ListView::pooled signal. That way you avoid using the CPU resources @@ -2257,6 +2258,23 @@ QQuickItemViewAttached *QQuickListViewPrivate::getAttachedObject(const QObject * items, at the expense of additional memory usage. \l{ListView::section}{Sections} have the same effect because they attach and elongate the section label to the first item within the section. + + \section1 Avoid Storing State in Delegates + + ListView's delegates are instantiated as needed and may be destroyed when + out of view. For an illustration of this, run the following example: + + \snippet qml/listview/stateInDelegate.qml ListView + + When an item is clicked, \c channelActivated is set to \c true. However, + because delegates can be \l {Reusing Items}{reused} and destroyed, all + state is lost when the view is moved far enough. When the delegate becomes + visible again, it will have its default, unmodified state (or, in the case + of an item that was reused, old state from a previous item). + + To avoid this, state should be stored in the model: + + \snippet qml/listview/stateInModel.qml ListView */ QQuickListView::QQuickListView(QQuickItem *parent) : QQuickItemView(*(new QQuickListViewPrivate), parent) |