@@ -14,6 +14,68 @@
1414 * along with this program. If not, see <http://www.gnu.org/licenses/>.
1515 */
1616
17+/*
18+ * Some documentation on how this thing works:
19+ *
20+ * A flickable has two very important concepts that define the top and
21+ * height of the flickable area.
22+ * The top is returned in minYExtent()
23+ * The height is set using setContentHeight()
24+ * By changing those two values we can make the list grow up or down
25+ * as needed. e.g. if we are in the middle of the list
26+ * and something that is above the viewport grows, since we do not
27+ * want to change the viewport because of that we just adjust the
28+ * minYExtent so that the list grows up.
29+ *
30+ * The implementation on the list relies on the delegateModel doing
31+ * most of the instantiation work. You call createItem() when you
32+ * need to create an item asking for it async or not. If returns null
33+ * it means the item will be created async and the model will call the
34+ * itemCreated slot with the item.
35+ *
36+ * updatePolish is the central point of dispatch for the work of the
37+ * class. It is called by the scene graph just before drawing the class.
38+ * In it we:
39+ * * Make sure all items are positioned correctly
40+ * * Add/Remove items if needed
41+ * * Update the content height if it was dirty
42+ *
43+ * m_visibleItems contains all the items we have created at the moment.
44+ * Actually not all of them are visible since it includes the ones
45+ * in the cache area we create asynchronously to help performance.
46+ * The first item in m_visibleItems has the m_firstVisibleIndex in
47+ * the model. If you actually want to know what is the first
48+ * item in the viewport you have to find the first non culled element
49+ * in m_visibleItems
50+ *
51+ * All the items (except the header) are childs of m_clipItem which
52+ * is a child of the contentItem() of the flickable (The contentItem()
53+ * is what actually 'moves' in a a flickable). This way
54+ * we can implement the clipping needed so we can have the header
55+ * shown in the middle of the list over the items without the items
56+ * leaking under the header in case it is transparent.
57+ *
58+ * The first item of m_visibleItems is the one that defines the
59+ * positions of all the rest of items (see updatePolish()) and
60+ * this is why sometimes we move it even if it's not the item
61+ * that has triggered the function (i.e. in itemGeometryChanged())
62+ *
63+ * m_visibleItems is a list of ListItem. Each ListItem
64+ * will contain a item and potentially a sectionItem. The sectionItem
65+ * is only there when the list is using sectionDelegate+sectionProperty
66+ * and this is the first item of the section. Each ListItem is vertically
67+ * layouted with the sectionItem first and then the item.
68+ *
69+ * For sectioning we also have a section item alone (m_topSectionItem)
70+ * that is used for the cases we need to show the sticky section item at
71+ * the top of the view.
72+ *
73+ * There are a few things that are not really implemented or tested properly
74+ * which we don't use at the moment like changing the model, changing
75+ * the section delegate, having a section delegate that changes its size, etc.
76+ * The known missing features are marked with TODOs along the code.
77+ */
78+
1779#include "listviewwithpageheader.h"
1880
1981#include <QDebug>
@@ -320,7 +382,7 @@ void ListViewWithPageHeader::viewportMoved(Qt::Orientations orient)
320382 }
321383 // We will be changing the clip item, need to accomadate for it
322384 // otherwise we move the firstItem down/up twice (unless the
323− // show header animation is running, where we want a different effect)
385+ // show header animation is running, where we want to keep the viewport stable)
324386 if (!m_headerShowAnimation->isRunning())
325387 diff += oldHeaderItemShownHeight - m_headerItemShownHeight;
326388 else
@@ -351,7 +413,6 @@ void ListViewWithPageHeader::createDelegateModel()
351413void ListViewWithPageHeader::refill()
352414{
353415 if (!isComponentComplete()) {
354− qWarning() << "Incomplete ListViewWithPageHeader::refill";
355416 return;
356417 }
357418