QQmlListCompositor Class
The QQmlListCompositor class provides a lookup table for filtered, or re-ordered list indexes. \internal
. More...
Header: | #include <QQmlListCompositor> |
Public Functions
QQmlListCompositor() | |
~QQmlListCompositor() | |
void | append(void *list, int index, int count, uint flags, QVector<Insert> *inserts = nullptr) |
void | clear() |
void | clearFlags(Group fromGroup, int from, int count, Group group, uint flags, QVector<Remove> *removes = nullptr) |
void | clearFlags(iterator from, int count, Group group, uint flags, QVector<Remove> *removes = nullptr) |
int | count(Group group) const |
iterator | find(Group group, int index) |
iterator | find(Group group, int index) const |
insert_iterator | findInsertPosition(Group group, int index) |
void | insert(Group group, int before, void *list, int index, int count, uint flags, QVector<Insert> *inserts = nullptr) |
iterator | insert(iterator before, void *list, int index, int count, uint flags, QVector<Insert> *inserts = nullptr) |
void | listItemsChanged(void *list, int index, int count, QVector<Change> *translatedChanges) |
void | listItemsInserted(void *list, int index, int count, QVector<Insert> *translatedInsertions) |
void | listItemsMoved(void *list, int from, int to, int count, QVector<Remove> *translatedRemovals, QVector<Insert> *translatedInsertions) |
void | listItemsRemoved(void *list, int index, int count, QVector<Remove> *translatedRemovals) |
void | move(Group fromGroup, int from, Group toGroup, int to, int count, Group moveGroup, QVector<Remove> *removes = nullptr, QVector<Insert> *inserts = nullptr) |
void | setFlags(Group fromGroup, int from, int count, Group group, int flags, QVector<Insert> *inserts = nullptr) |
void | setFlags(iterator from, int count, Group group, uint flags, QVector<Insert> *inserts = nullptr) |
void | setGroupCount(int count) |
Detailed Description
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 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.
Member Function Documentation
QQmlListCompositor::QQmlListCompositor()
Constructs an empty list compositor.
[noexcept]
QQmlListCompositor::~QQmlListCompositor()
Destroys a list compositor.
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.
void QQmlListCompositor::clear()
Clears the contents of a compositor.
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.
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.
int QQmlListCompositor::count(Group group) const
Returns the number of items that belong to a group.
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.
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.
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.
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.
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.
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.
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.
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.
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.
void QQmlListCompositor::move(Group fromGroup, int from, Group toGroup, int to, int count, Group moveGroup, QVector<Remove> *removes = nullptr, QVector<Insert> *inserts = nullptr)
\internal
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.
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.
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.
void QQmlListCompositor::setGroupCount(int count)
Sets the number (count) of possible groups that items may belong to in a compositor.