QQmlListCompositor Class Reference

The QQmlListCompositor class provides a lookup table for filtered, or re-ordered list indexes. More...

#include <qqmllistcompositor_p.h>

Collaboration diagram for QQmlListCompositor:

Classes
struct	Change
struct	Insert
class	insert_iterator
class	iterator
class	Range
struct	Remove

Public Types
enum	{ MinimumGroupCount = 3 , MaximumGroupCount = 11 }
enum	Group { Cache = 0 , Default = 1 , Persisted = 2 }
enum	Flag {   CacheFlag = 1 << Cache , DefaultFlag = 1 << Default , PersistedFlag = 1 << Persisted , PrependFlag = 0x10000000 ,   AppendFlag = 0x20000000 , UnresolvedFlag = 0x40000000 , MovedFlag = 0x80000000 , GroupMask = ~(PrependFlag | AppendFlag | UnresolvedFlag | MovedFlag | CacheFlag) }

Public Member Functions
	QQmlListCompositor ()
	Constructs an empty list compositor.
	~QQmlListCompositor ()
	Destroys a list compositor.
int	defaultGroups () const
void	setDefaultGroups (int groups)
void	setDefaultGroup (Group group)
void	clearDefaultGroup (Group group)
void	setRemoveGroups (int groups)
void	setGroupCount (int count)
	Sets the number (count) of possible groups that items may belong to in a compositor.
int	count (Group group) const
	Returns the number of items that belong to a group.
iterator	find (Group group, int index)
	Returns an iterator representing the item at index in a group.
iterator	find (Group group, int index) const
	Returns an iterator representing the item at index in a group.
insert_iterator	findInsertPosition (Group group, int index)
	Returns an iterator representing an insert position in front of the item at index in a group.
const iterator &	end ()
void	append (void *list, int index, int count, uint flags, QVector< Insert > *inserts=nullptr)
	Appends a range of count indexes starting at index from a list into a compositor with the given flags.
void	insert (Group group, int before, void *list, int index, int count, uint flags, QVector< Insert > *inserts=nullptr)
	Inserts a range of count indexes starting at index from a list with the given flags into a group at index before.
iterator	insert (iterator before, void *list, int index, int count, uint flags, QVector< Insert > *inserts=nullptr)
	Inserts a range of count indexes starting at index from a list with the given flags into a compositor at position before.
void	setFlags (Group fromGroup, int from, int count, Group group, int flags, QVector< Insert > *inserts=nullptr)
	Sets the given flags flags on count items belonging to group starting at the position identified by fromGroup and the index from.
void	setFlags (iterator from, int count, Group group, uint flags, QVector< Insert > *inserts=nullptr)
	Sets the given flags flags on count items belonging to group starting at the position from.
void	setFlags (Group fromGroup, int from, int count, uint flags, QVector< Insert > *inserts=nullptr)
void	setFlags (const iterator from, int count, uint flags, QVector< Insert > *inserts=nullptr)
void	clearFlags (Group fromGroup, int from, int count, Group group, uint flags, QVector< Remove > *removals=nullptr)
	Clears the given flags flags on count items belonging to group starting at the position from.
void	clearFlags (iterator from, int count, Group group, uint flags, QVector< Remove > *removals=nullptr)
	Clears the given flags flags on count items belonging to group starting at the position identified by fromGroup and the index from.
void	clearFlags (Group fromGroup, int from, int count, uint flags, QVector< Remove > *removals=nullptr)
void	clearFlags (const iterator &from, int count, uint flags, QVector< Remove > *removals=nullptr)
bool	verifyMoveTo (Group fromGroup, int from, Group toGroup, int to, int count, Group group) const
void	move (Group fromGroup, int from, Group toGroup, int to, int count, Group group, QVector< Remove > *removals=nullptr, QVector< Insert > *inserts=nullptr)
void	clear ()
	Clears the contents of a compositor.
void	listItemsInserted (void *list, int index, int count, QVector< Insert > *inserts)
	Updates the contents of a compositor when count items are inserted into a list at index.
void	listItemsRemoved (void *list, int index, int count, QVector< Remove > *removals)
	Updates the contents of a compositor when count items are removed from a list at index.
void	listItemsMoved (void *list, int from, int to, int count, QVector< Remove > *removals, QVector< Insert > *inserts)
	Updates the contents of a compositor when count items are removed from a list at index.
void	listItemsChanged (void *list, int index, int count, QVector< Change > *changes)
	Translates the positions of count changed items at index in a list.
void	transition (Group from, Group to, QVector< QQmlChangeSet::Change > *removes, QVector< QQmlChangeSet::Change > *inserts)

Friends
Q_AUTOTEST_EXPORT QDebug	operator<< (QDebug debug, const QQmlListCompositor &list)

Detailed Description

The QQmlListCompositor class provides a lookup table for filtered, or re-ordered list indexes.

QQmlListCompositor is intended as an aid for developing proxy models. It doesn't however directly proxy a list or model, instead a range of indexes from one or many lists can be inserted into the compositor and then categorized and shuffled around and it will manage the task of translating from an index in the combined space into an index in a particular list.

Within a compositor indexes are categorized into groups where a group is a sub-set of the total indexes referenced by the compositor, each with an address space ranging from 0 to the number of indexes in the group - 1. Group memberships are independent of each other with the one exception that items always retain the same order so if an index is moved within a group, its position in other groups will change as well.

The iterator classes encapsulate information about a specific position in a compositor group. This includes a source list, the index of an item within that list and the groups that item is a member of. The iterator for a specific position in a group can be retrieved with the find() function and the addition and subtraction operators of the iterators can be used to navigate to adjacent items in the same group.

Items can be added to the compositor with the append() and insert() functions, group membership can be changed with the setFlags() and clearFlags() functions, and the position of items in the compositor can be changed with the move() function. Each of these functions optionally returns a list of the changes made to indexes within each group which can then be propagated to view so that it can correctly refresh its contents; e.g. 3 items removed at index 6, and 5 items inserted at index 1. The notification changes are always ordered from the start of the list to the end and accumulate, so if 5 items are removed at index 4, one is skipped and then 3 move are removed, the changes returned are 5 items removed at index 4, followed by 3 items removed at index 4.

When the contents of a source list change, the mappings within the compositor can be updated with the listItemsInserted(), listItemsRemoved(), listItemsMoved(), and listItemsChanged() functions. Like the direct manipulation functions these too return a list of group indexes affected by the change. If items are removed from a source list they are also removed from any groups they belong to with the one exception being items belonging to the \l Cache group. When items belonging to this group are removed the list, index, and other group membership information are discarded but Cache membership is retained until explicitly removed. This allows the cache index to be retained until cached resources for that item are actually released.

Internally the index mapping is stored as a list of Range objects, each has a list identifier, a start index, a count, and a set of flags which represent group membership and some other properties. The group index of a range is the sum of all preceding ranges that are members of that group. To avoid the inefficiency of iterating over potentially all ranges when looking for a specific index, each time a lookup is done the range and its indexes are cached and the next lookup is done relative to this. This works out to near constant time in most relevant use cases because successive index lookups are most frequently adjacent. The total number of ranges is often quite small, which helps as well. If there is a need for faster random access then a skip list like index may be an appropriate addition.

See also

DelegateModel

Definition at line 27 of file qqmllistcompositor_p.h.

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
MinimumGroupCount
MaximumGroupCount

Definition at line 30 of file qqmllistcompositor_p.h.

Flag

enum QQmlListCompositor::Flag

Enumerator
CacheFlag
DefaultFlag
PersistedFlag
PrependFlag
AppendFlag
UnresolvedFlag
MovedFlag
GroupMask

Definition at line 39 of file qqmllistcompositor_p.h.

Group

enum QQmlListCompositor::Group

Enumerator
Cache
Default
Persisted

Definition at line 32 of file qqmllistcompositor_p.h.

Constructor & Destructor Documentation

QQmlListCompositor()

QQmlListCompositor::QQmlListCompositor

(

)

Constructs an empty list compositor.

Definition at line 251 of file qqmllistcompositor.cpp.

~QQmlListCompositor()

QQmlListCompositor::~QQmlListCompositor

(

)

Destroys a list compositor.

Definition at line 265 of file qqmllistcompositor.cpp.

References next, and QQmlListCompositor::Range::next.

Member Function Documentation

append()

void QQmlListCompositor::append	(	void *	list,
		int	index,
		int	count,
		uint	flags,
		QVector< Insert > *	inserts = nullptr )

Appends a range of count indexes starting at index from a list into a compositor with the given flags.

If supplied the inserts list will be populated with the positions of the inserted items in each group.

Definition at line 393 of file qqmllistcompositor.cpp.

References insert(), list, and QT_QML_TRACE_LISTCOMPOSITOR.

Here is the call graph for this function:

clear()

void QQmlListCompositor::clear

(

)

Clears the contents of a compositor.

Definition at line 905 of file qqmllistcompositor.cpp.

References Default, QQmlListCompositor::Range::next, and QT_QML_TRACE_LISTCOMPOSITOR.

clearDefaultGroup()

void QQmlListCompositor::clearDefaultGroup ( Group group )

inline

Definition at line 182 of file qqmllistcompositor_p.h.

clearFlags() [1/4]

void QQmlListCompositor::clearFlags ( const iterator & from, int count, uint flags, QVector< Remove > * removals = nullptr )

inline

Definition at line 208 of file qqmllistcompositor_p.h.

References QQmlListCompositor::iterator::group.

clearFlags() [2/4]

void QQmlListCompositor::clearFlags	(	Group	fromGroup,
		int	from,
		int	count,
		Group	group,
		uint	flags,
		QVector< Remove > *	removes = nullptr )

Clears the given flags flags on count items belonging to group starting at the position from.

If supplied the removes list will be populated with remove notifications for affected groups.

Definition at line 587 of file qqmllistcompositor.cpp.

References clearFlags(), find(), and QT_QML_TRACE_LISTCOMPOSITOR.

Referenced by clearFlags(), QQmlDelegateModelPrivate::itemsRemoved(), QQmlDelegateModelPrivate::removeCacheItem(), QQmlDelegateModelPrivate::removeGroups(), and QQmlDelegateModelPrivate::setGroups().

Here is the call graph for this function:

Here is the caller graph for this function:

clearFlags() [3/4]

void QQmlListCompositor::clearFlags ( Group fromGroup, int from, int count, uint flags, QVector< Remove > * removals = nullptr )

inline

Definition at line 206 of file qqmllistcompositor_p.h.

clearFlags() [4/4]

void QQmlListCompositor::clearFlags	(	iterator	from,
		int	count,
		Group	group,
		uint	flags,
		QVector< Remove > *	removes = nullptr )

Clears the given flags flags on count items belonging to group starting at the position identified by fromGroup and the index from.

If supplied the removes list will be populated with remove notifications for affected groups.

Definition at line 601 of file qqmllistcompositor.cpp.

References QQmlListCompositor::Range::append(), AppendFlag, CacheFlag, QQmlListCompositor::Range::count, QQmlListCompositor::iterator::decrementIndexes(), QQmlListCompositor::Range::end(), QQmlListCompositor::Range::flags, QQmlListCompositor::iterator::incrementIndexes(), QQmlListCompositor::Range::index, insert(), QQmlListCompositor::Range::list, QQmlListCompositor::Range::next, QQmlListCompositor::iterator::offset, PrependFlag, QQmlListCompositor::Range::previous, qMin(), QT_QML_TRACE_LISTCOMPOSITOR, QT_QML_VERIFY_LISTCOMPOSITOR, and UnresolvedFlag.

Here is the call graph for this function:

count()

int QQmlListCompositor::count

(

Group

group

)

const

Returns the number of items that belong to a group.

Definition at line 315 of file qqmllistcompositor.cpp.

References QQmlListCompositor::iterator::index.

Referenced by QQmlDelegateModelPrivate::addCacheItem(), QQmlDelegateModelPrivate::delegateChanged(), QQmlDelegateModelPrivate::itemsInserted(), QQmlDelegateModelPrivate::itemsMoved(), QQmlDelegateModelPrivate::itemsRemoved(), QQmlDelegateModelPrivate::itemsRemoved(), QQmlDelegateModelPrivate::object(), and QQmlDelegateModelPrivate::removeCacheItem().

Here is the caller graph for this function:

defaultGroups()

int QQmlListCompositor::defaultGroups ( ) const

inline

Definition at line 179 of file qqmllistcompositor_p.h.

end()

const iterator & QQmlListCompositor::end ( )

inline

Definition at line 191 of file qqmllistcompositor_p.h.

find() [1/2]

QQmlListCompositor::iterator QQmlListCompositor::find	(	Group	group,
		int	index )

Returns an iterator representing the item at index in a group.

The index must be between 0 and count(group) - 1.

Definition at line 326 of file qqmllistcompositor.cpp.

References QQmlListCompositor::iterator::index, QQmlListCompositor::Range::inGroup(), QQmlListCompositor::Range::next, Q_ASSERT, QT_QML_TRACE_LISTCOMPOSITOR, QT_QML_VERIFY_LISTCOMPOSITOR, and QQmlListCompositor::iterator::setGroup().

Referenced by clearFlags(), find(), move(), QQmlDelegateModelPrivate::object(), setFlags(), QQmlDelegateModelPrivate::setGroups(), QQmlDelegateModelPrivate::variantValue(), and verifyMoveTo().

Here is the call graph for this function:

Here is the caller graph for this function:

find() [2/2]

QQmlListCompositor::iterator QQmlListCompositor::find	(	Group	group,
		int	index ) const

Returns an iterator representing the item at index in a group.

The index must be between 0 and count(group) - 1.

Definition at line 350 of file qqmllistcompositor.cpp.

References find().

Here is the call graph for this function:

findInsertPosition()

QQmlListCompositor::insert_iterator QQmlListCompositor::findInsertPosition	(	Group	group,
		int	index )

Returns an iterator representing an insert position in front of the item at index in a group.

The iterator for an insert position can sometimes resolve to a different Range than a regular iterator. This is because when items are inserted on a boundary between Ranges, if the first range has the Append flag set then the items should be inserted into that range to ensure that the append position for the existing range remains after the insert position.

The index must be between 0 and count(group) - 1.

Definition at line 367 of file qqmllistcompositor.cpp.

References QQmlListCompositor::iterator::index, it, QQmlListCompositor::Range::next, Q_ASSERT, and QT_QML_TRACE_LISTCOMPOSITOR.

Referenced by insert().

Here is the caller graph for this function:

insert() [1/2]

void QQmlListCompositor::insert	(	Group	group,
		int	before,
		void *	list,
		int	index,
		int	count,
		uint	flags,
		QVector< Insert > *	inserts = nullptr )

Inserts a range of count indexes starting at index from a list with the given flags into a group at index before.

If supplied the inserts list will be populated with the positions of items inserted into each group.

Definition at line 408 of file qqmllistcompositor.cpp.

References findInsertPosition(), insert(), list, and QT_QML_TRACE_LISTCOMPOSITOR.

Referenced by append(), clearFlags(), QQmlDelegateModelPrivate::insert(), insert(), insert(), move(), and setFlags().

Here is the call graph for this function:

Here is the caller graph for this function:

insert() [2/2]

QQmlListCompositor::iterator QQmlListCompositor::insert	(	iterator	before,
		void *	list,
		int	index,
		int	count,
		uint	flags,
		QVector< Insert > *	inserts = nullptr )

Inserts a range of count indexes starting at index from a list with the given flags into a compositor at position before.

If supplied the inserts list will be populated with the positions of items inserted into each group.

Definition at line 423 of file qqmllistcompositor.cpp.

References AppendFlag, QQmlListCompositor::Range::count, QQmlListCompositor::Range::end(), QQmlListCompositor::Range::flags, GroupMask, QQmlListCompositor::iterator::incrementIndexes(), QQmlListCompositor::Range::index, insert(), list, QQmlListCompositor::Range::list, QQmlListCompositor::Range::next, QQmlListCompositor::iterator::offset, QQmlListCompositor::Range::previous, QT_QML_TRACE_LISTCOMPOSITOR, and QT_QML_VERIFY_LISTCOMPOSITOR.

Here is the call graph for this function:

listItemsChanged()

void QQmlListCompositor::listItemsChanged	(	void *	list,
		int	index,
		int	count,
		QVector< Change > *	translatedChanges )

Translates the positions of count changed items at index in a list.

The translatedChanges list is populated with change notifications for the affected groups.

Definition at line 1294 of file qqmllistcompositor.cpp.

References list, listItemsChanged(), Q_ASSERT, and QT_QML_TRACE_LISTCOMPOSITOR.

Referenced by listItemsChanged().

Here is the call graph for this function:

Here is the caller graph for this function:

listItemsInserted()

void QQmlListCompositor::listItemsInserted	(	void *	list,
		int	index,
		int	count,
		QVector< Insert > *	translatedInsertions )

Updates the contents of a compositor when count items are inserted into a list at index.

This corrects the indexes of each range for that list in the compositor, splitting the range in two if the insert index is in the middle of that range. If a range at the insert position has the Prepend flag set then a new range will be inserted at that position with the groups specified in defaultGroups(). If the insert index corresponds to the end of a range with the Append flag set a new range will be inserted before the end of the append range.

The translatedInsertions list is populated with insert notifications for affected groups.

Definition at line 1023 of file qqmllistcompositor.cpp.

References list, listItemsInserted(), Q_ASSERT, and QT_QML_TRACE_LISTCOMPOSITOR.

Referenced by listItemsInserted(), and listItemsMoved().

Here is the call graph for this function:

Here is the caller graph for this function:

listItemsMoved()

void QQmlListCompositor::listItemsMoved	(	void *	list,
		int	from,
		int	to,
		int	count,
		QVector< Remove > *	translatedRemovals,
		QVector< Insert > *	translatedInsertions )

Updates the contents of a compositor when count items are removed from a list at index.

Ranges that intersect the specified range are removed from the compositor and the indexes of ranges after index + count are updated.

The translatedRemovals and translatedInserts lists are populated with move notifications for the affected groups.

Definition at line 1234 of file qqmllistcompositor.cpp.

References list, listItemsInserted(), listItemsRemoved(), Q_ASSERT, and QT_QML_TRACE_LISTCOMPOSITOR.

Here is the call graph for this function:

listItemsRemoved()

void QQmlListCompositor::listItemsRemoved	(	void *	list,
		int	index,
		int	count,
		QVector< Remove > *	translatedRemovals )

Updates the contents of a compositor when count items are removed from a list at index.

Ranges that intersect the specified range are removed from the compositor and the indexes of ranges after index + count are updated.

The translatedRemovals list is populated with remove notifications for the affected groups.

Definition at line 1212 of file qqmllistcompositor.cpp.

References list, listItemsRemoved(), Q_ASSERT, and QT_QML_TRACE_LISTCOMPOSITOR.

Referenced by listItemsMoved(), and listItemsRemoved().

Here is the call graph for this function:

Here is the caller graph for this function:

move()

void QQmlListCompositor::move	(	Group	fromGroup,
		int	from,
		Group	toGroup,
		int	to,
		int	count,
		Group	moveGroup,
		QVector< Remove > *	removes = nullptr,
		QVector< Insert > *	inserts = nullptr )

Moves count items belonging to moveGroup from the index from in fromGroup to the index to in toGroup.

If removes and inserts are not null they will be populated with per group notifications of the items moved.

Definition at line 730 of file qqmllistcompositor.cpp.

References AppendFlag, find(), QQmlListCompositor::Range::flags, i, insert(), QQmlListCompositor::Range::list, next, QQmlListCompositor::Range::next, PrependFlag, QQmlListCompositor::Range::previous, Q_ASSERT, qMin(), QT_QML_TRACE_LISTCOMPOSITOR, QT_QML_VERIFY_LISTCOMPOSITOR, QQmlListCompositor::iterator::setGroup(), and verifyMoveTo().

Here is the call graph for this function:

setDefaultGroup()

void QQmlListCompositor::setDefaultGroup ( Group group )

inline

Definition at line 181 of file qqmllistcompositor_p.h.

setDefaultGroups()

void QQmlListCompositor::setDefaultGroups ( int groups )

inline

Definition at line 180 of file qqmllistcompositor_p.h.

setFlags() [1/4]

void QQmlListCompositor::setFlags ( const iterator from, int count, uint flags, QVector< Insert > * inserts = nullptr )

inline

Definition at line 201 of file qqmllistcompositor_p.h.

References QQmlListCompositor::iterator::group.

setFlags() [2/4]

void QQmlListCompositor::setFlags	(	Group	fromGroup,
		int	from,
		int	count,
		Group	group,
		int	flags,
		QVector< Insert > *	inserts = nullptr )

Sets the given flags flags on count items belonging to group starting at the position identified by fromGroup and the index from.

If supplied the inserts list will be populated with insert notifications for affected groups.

Definition at line 477 of file qqmllistcompositor.cpp.

References find(), QT_QML_TRACE_LISTCOMPOSITOR, and setFlags().

Referenced by QQmlDelegateModelPrivate::addCacheItem(), QQmlDelegateModelPrivate::addGroups(), setFlags(), setFlags(), and QQmlDelegateModelPrivate::setGroups().

Here is the call graph for this function:

Here is the caller graph for this function:

setFlags() [3/4]

void QQmlListCompositor::setFlags ( Group fromGroup, int from, int count, uint flags, QVector< Insert > * inserts = nullptr )

inline

Definition at line 199 of file qqmllistcompositor_p.h.

setFlags() [4/4]

void QQmlListCompositor::setFlags	(	iterator	from,
		int	count,
		Group	group,
		uint	flags,
		QVector< Insert > *	inserts = nullptr )

Sets the given flags flags on count items belonging to group starting at the position from.

If supplied the inserts list will be populated with insert notifications for affected groups.

Definition at line 491 of file qqmllistcompositor.cpp.

References QQmlListCompositor::Range::append(), AppendFlag, CacheFlag, QQmlListCompositor::Range::count, QQmlListCompositor::Range::end(), QQmlListCompositor::Range::flags, QQmlListCompositor::iterator::group, QQmlListCompositor::iterator::incrementIndexes(), QQmlListCompositor::Range::index, insert(), QQmlListCompositor::Range::list, QQmlListCompositor::Range::next, QQmlListCompositor::iterator::offset, QQmlListCompositor::Range::previous, qMin(), QT_QML_TRACE_LISTCOMPOSITOR, QT_QML_VERIFY_LISTCOMPOSITOR, and setFlags().

Here is the call graph for this function:

setGroupCount()

void QQmlListCompositor::setGroupCount

(

int

count

)

Sets the number (count) of possible groups that items may belong to in a compositor.

Definition at line 304 of file qqmllistcompositor.cpp.

References Default.

setRemoveGroups()

void QQmlListCompositor::setRemoveGroups ( int groups )

inline

Definition at line 183 of file qqmllistcompositor_p.h.

Referenced by QQmlDelegateModelPrivate::init().

Here is the caller graph for this function:

transition()

void QQmlListCompositor::transition	(	Group	from,
		Group	to,
		QVector< QQmlChangeSet::Change > *	removes,
		QVector< QQmlChangeSet::Change > *	inserts )

Definition at line 1304 of file qqmllistcompositor.cpp.

References QSet< T >::count(), Default, it, and QQmlListCompositor::Range::next.

Referenced by QQmlDelegateModelPrivate::updateFilterGroup().

Here is the call graph for this function:

Here is the caller graph for this function:

verifyMoveTo()

bool QQmlListCompositor::verifyMoveTo	(	Group	fromGroup,
		int	from,
		Group	toGroup,
		int	to,
		int	count,
		Group	group ) const

Definition at line 695 of file qqmllistcompositor.cpp.

References find(), QQmlListCompositor::iterator::index, and qMin().

Referenced by move().

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

operator<<

Q_AUTOTEST_EXPORT QDebug operator<< ( QDebug debug, const QQmlListCompositor & list )

friend

Writes the contents of list to debug.

Definition at line 1426 of file qqmllistcompositor.cpp.

---

The documentation for this class was generated from the following files:

• qtdeclarative/src/qmlmodels/qqmllistcompositor_p.h (0dc4fd240a2897c5c443a0ef6d84c416843e4938)
• qtdeclarative/src/qmlmodels/qqmllistcompositor.cpp (0dc4fd240a2897c5c443a0ef6d84c416843e4938)