QItemSelection Class Reference

The QItemSelection class manages information about selected items in a model. More...

#include <qitemselectionmodel.h>

Inheritance diagram for QItemSelection:

Public Functions
bool	contains (const QModelIndex &index) const
	Returns true if the selection contains the given index; otherwise returns false. More...
QModelIndexList	indexes () const
	Returns a list of model indexes that correspond to the selected items. More...
void	merge (const QItemSelection &other, QItemSelectionModel::SelectionFlags command)
	Merges the other selection with this QItemSelection using the command given. More...
	QItemSelection ()
	Constructs an empty selection. More...
	QItemSelection (const QModelIndex &topLeft, const QModelIndex &bottomRight)
	Constructs an item selection that extends from the top-left model item, specified by the topLeft index, to the bottom-right item, specified by bottomRight. More...
void	select (const QModelIndex &topLeft, const QModelIndex &bottomRight)
	Adds the items in the range that extends from the top-left model item, specified by the topLeft index, to the bottom-right item, specified by bottomRight to the list. More...
Public Functions inherited from QList< QItemSelectionRange >
void	append (const QItemSelectionRange &t)
	Inserts value at the end of the list. More...
void	append (const QList< QItemSelectionRange > &t)
	Appends the items of the value list to this list. More...
const QItemSelectionRange &	at (int i) const
	Returns the item at index position i in the list. More...
QItemSelectionRange &	back ()
	This function is provided for STL compatibility. More...
const QItemSelectionRange &	back () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
iterator	begin ()
	Returns an STL-style iterator pointing to the first item in the list. More...
const_iterator	begin () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
void	clear ()
	Removes all items from the list. More...
const_iterator	constBegin () const
	Returns a const STL-style iterator pointing to the first item in the list. More...
const_iterator	constEnd () const
	Returns a const STL-style iterator pointing to the imaginary item after the last item in the list. More...
QBool	contains (const QItemSelectionRange &t) const
	Returns true if the list contains an occurrence of value; otherwise returns false. More...
int	count (const QItemSelectionRange &t) const
	Returns the number of occurrences of value in the list. More...
int	count () const
	Returns the number of items in the list. More...
void	detach ()
void	detachShared ()
	This prevents needless mallocs, and makes QList more exception safe in case of cleanup work done in destructors on empty lists. More...
bool	empty () const
	This function is provided for STL compatibility. More...
iterator	end ()
	Returns an STL-style iterator pointing to the imaginary item after the last item in the list. More...
const_iterator	end () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
bool	endsWith (const QItemSelectionRange &t) const
	Returns true if this list is not empty and its last item is equal to value; otherwise returns false. More...
iterator	erase (iterator pos)
	Removes the item associated with the iterator pos from the list, and returns an iterator to the next item in the list (which may be end()). More...
iterator	erase (iterator first, iterator last)
	Removes all the items from begin up to (but not including) end. More...
QItemSelectionRange &	first ()
	Returns a reference to the first item in the list. More...
const QItemSelectionRange &	first () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
QItemSelectionRange &	front ()
	This function is provided for STL compatibility. More...
const QItemSelectionRange &	front () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
int	indexOf (const QItemSelectionRange &t, int from=0) const
	Returns the index position of the first occurrence of value in the list, searching forward from index position from. More...
void	insert (int i, const QItemSelectionRange &t)
	Inserts value at index position i in the list. More...
iterator	insert (iterator before, const QItemSelectionRange &t)
	Inserts value in front of the item pointed to by the iterator before. More...
bool	isDetached () const
bool	isEmpty () const
	Returns true if the list contains no items; otherwise returns false. More...
bool	isSharedWith (const QList< QItemSelectionRange > &other) const
QItemSelectionRange &	last ()
	Returns a reference to the last item in the list. More...
const QItemSelectionRange &	last () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
int	lastIndexOf (const QItemSelectionRange &t, int from=-1) const
	Returns the index position of the last occurrence of value in the list, searching backward from index position from. More...
int	length () const
	This function is identical to count(). More...
QList< QItemSelectionRange >	mid (int pos, int length=-1) const
	Returns a list whose elements are copied from this list, starting at position pos. More...
void	move (int from, int to)
	Moves the item at index position from to index position to. More...
bool	operator!= (const QList< QItemSelectionRange > &l) const
	Returns true if other is not equal to this list; otherwise returns false. More...
QList< QItemSelectionRange >	operator+ (const QList< QItemSelectionRange > &l) const
	Returns a list that contains all the items in this list followed by all the items in the other list. More...
QList< QItemSelectionRange > &	operator+= (const QList< QItemSelectionRange > &l)
	Appends the items of the other list to this list and returns a reference to this list. More...
QList< QItemSelectionRange > &	operator+= (const QItemSelectionRange &t)
	Appends value to the list. More...
QList< QItemSelectionRange > &	operator<< (const QList< QItemSelectionRange > &l)
	Appends the items of the other list to this list and returns a reference to this list. More...
QList< QItemSelectionRange > &	operator<< (const QItemSelectionRange &t)
	Appends value to the list. More...
QList< QItemSelectionRange > &	operator= (const QList< QItemSelectionRange > &l)
	Assigns other to this list and returns a reference to this list. More...
bool	operator== (const QList< QItemSelectionRange > &l) const
	Returns true if other is equal to this list; otherwise returns false. More...
const QItemSelectionRange &	operator[] (int i) const
	Same as at(). More...
QItemSelectionRange &	operator[] (int i)
	Returns the item at index position i as a modifiable reference. More...
void	pop_back ()
	This function is provided for STL compatibility. More...
void	pop_front ()
	This function is provided for STL compatibility. More...
void	prepend (const QItemSelectionRange &t)
	Inserts value at the beginning of the list. More...
void	push_back (const QItemSelectionRange &t)
	This function is provided for STL compatibility. More...
void	push_front (const QItemSelectionRange &t)
	This function is provided for STL compatibility. More...
	QList ()
	Constructs an empty list. More...
	QList (const QList< QItemSelectionRange > &l)
	Constructs a copy of other. More...
int	removeAll (const QItemSelectionRange &t)
	Removes all occurrences of value in the list and returns the number of entries removed. More...
void	removeAt (int i)
	Removes the item at index position i. More...
void	removeFirst ()
	Removes the first item in the list. More...
void	removeLast ()
	Removes the last item in the list. More...
bool	removeOne (const QItemSelectionRange &t)
	Removes the first occurrence of value in the list and returns true on success; otherwise returns false. More...
void	replace (int i, const QItemSelectionRange &t)
	Replaces the item at index position i with value. More...
void	reserve (int size)
	Reserve space for alloc elements. More...
void	setSharable (bool sharable)
int	size () const
	Returns the number of items in the list. More...
bool	startsWith (const QItemSelectionRange &t) const
	Returns true if this list is not empty and its first item is equal to value; otherwise returns false. More...
void	swap (QList< QItemSelectionRange > &other)
	Swaps list other with this list. More...
void	swap (int i, int j)
	Exchange the item at index position i with the item at index position j. More...
QItemSelectionRange	takeAt (int i)
	Removes the item at index position i and returns it. More...
QItemSelectionRange	takeFirst ()
	Removes the first item in the list and returns it. More...
QItemSelectionRange	takeLast ()
	Removes the last item in the list and returns it. More...
QSet< QItemSelectionRange >	toSet () const
	Returns a QSet object with the data contained in this QList. More...
std::list< QItemSelectionRange >	toStdList () const
	Returns a std::list object with the data contained in this QList. More...
QVector< QItemSelectionRange >	toVector () const
	Returns a QVector object with the data contained in this QList. More...
QItemSelectionRange	value (int i) const
	Returns the value at index position i in the list. More...
QItemSelectionRange	value (int i, const QItemSelectionRange &defaultValue) const
	If the index i is out of bounds, the function returns defaultValue. More...
	~QList ()
	Destroys the list. More...

Static Public Functions
static void	split (const QItemSelectionRange &range, const QItemSelectionRange &other, QItemSelection *result)
	Splits the selection range using the selection other range. More...
Static Public Functions inherited from QList< QItemSelectionRange >
static QList< QItemSelectionRange >	fromSet (const QSet< QItemSelectionRange > &set)
	Returns a QList object with the data contained in set. More...
static QList< QItemSelectionRange >	fromStdList (const std::list< QItemSelectionRange > &list)
	Returns a QList object with the data contained in list. More...
static QList< QItemSelectionRange >	fromVector (const QVector< QItemSelectionRange > &vector)
	Returns a QList object with the data contained in vector. More...

Additional Inherited Members
Public Types inherited from QList< QItemSelectionRange >
typedef const value_type *	const_pointer
	Typedef for const T *. More...
typedef const value_type &	const_reference
	Typedef for const T &. More...
typedef const_iterator	ConstIterator
	Qt-style synonym for QList::const_iterator. More...
typedef qptrdiff	difference_type
	Typedef for ptrdiff_t. More...
typedef iterator	Iterator
	Qt-style synonym for QList::iterator. More...
typedef value_type *	pointer
	Typedef for T *. More...
typedef value_type &	reference
	Typedef for T &. More...
typedef int	size_type
	Typedef for int. More...
typedef QItemSelectionRange	value_type
	Typedef for T. More...
Public Variables inherited from QList< QItemSelectionRange >
QListData::Data *	d
QListData	p
Related Functions inherited from QList< QItemSelectionRange >
QDataStream &	operator<< (QDataStream &out, const QList< QItemSelectionRange > &list)
	Writes the list list to stream out. More...
QDataStream &	operator>> (QDataStream &in, QList< QItemSelectionRange > &list)
	Reads a list from stream in into list. More...

Detailed Description

The QItemSelection class manages information about selected items in a model.

A QItemSelection describes the items in a model that have been selected by the user. A QItemSelection is basically a list of selection ranges, see QItemSelectionRange. It provides functions for creating and manipulating selections, and selecting a range of items from a model.

The QItemSelection class is one of the Model/View Classes and is part of Qt's Model/View Programming{model/view framework}.

An item selection can be constructed and initialized to contain a range of items from an existing model. The following example constructs a selection that contains a range of items from the given model, beginning at the topLeft, and ending at the bottomRight.

QItemSelection *selection = new QItemSelection(topLeft, bottomRight);

An empty item selection can be constructed, and later populated as required. So, if the model is going to be unavailable when we construct the item selection, we can rewrite the above code in the following way:

QItemSelection *selection = new QItemSelection();
...
selection->select(topLeft, bottomRight);

QItemSelection saves memory, and avoids unnecessary work, by working with selection ranges rather than recording the model item index for each item in the selection. Generally, an instance of this class will contain a list of non-overlapping selection ranges.

Use merge() to merge one item selection into another without making overlapping ranges. Use split() to split one selection range into smaller ranges based on a another selection range.

See also

{Model/View Programming}, QItemSelectionModel

Definition at line 231 of file qitemselectionmodel.h.

Constructors and Destructors

QItemSelection() [1/2]

QItemSelection::QItemSelection ( )

inline

Constructs an empty selection.

Definition at line 234 of file qitemselectionmodel.h.

{}

QItemSelection() [2/2]

QItemSelection::QItemSelection	(	const QModelIndex &	topLeft,
		const QModelIndex &	bottomRight
	)

Constructs an item selection that extends from the top-left model item, specified by the topLeft index, to the bottom-right item, specified by bottomRight.

Definition at line 451 of file qitemselectionmodel.cpp.

{
    select(topLeft, bottomRight);
}

Functions

contains()

bool QItemSelection::contains

(

const QModelIndex &

index

)

const

Returns true if the selection contains the given index; otherwise returns false.

Definition at line 491 of file qitemselectionmodel.cpp.

{
    if (index.flags() & Qt::ItemIsSelectable) {
        QList<QItemSelectionRange>::const_iterator it = begin();
        for (; it != end(); ++it)
            if ((*it).contains(index))
                return true;
    }
    return false;
}

indexes()

QModelIndexList QItemSelection::indexes

(

)

const

Returns a list of model indexes that correspond to the selected items.

Definition at line 506 of file qitemselectionmodel.cpp.

Referenced by QCompleterPrivate::_q_completionSelected(), QTreeWidgetPrivate::_q_selectionChanged(), QAbstractItemViewPrivate::clearOrRemove(), QAbstractProxyModel::mapSelectionFromSource(), QAbstractProxyModel::mapSelectionToSource(), QItemSelectionModel::selectedIndexes(), QTableView::selectionChanged(), QListView::selectionChanged(), and QTreeView::selectionChanged().

{
    QModelIndexList result;
    QList<QItemSelectionRange>::const_iterator it = begin();
    for (; it != end(); ++it)
        indexesFromRange(*it, result);
    return result;
}

merge()

void QItemSelection::merge	(	const QItemSelection &	other,
		QItemSelectionModel::SelectionFlags	command
	)

Merges the other selection with this QItemSelection using the command given.

This method guarantees that no ranges are overlapping.

Note that only QItemSelectionModel::Select, QItemSelectionModel::Deselect, and QItemSelectionModel::Toggle are supported.

See also

split()

Definition at line 525 of file qitemselectionmodel.cpp.

Referenced by QItemSelectionModel::columnIntersectsSelection(), QItemSelectionModelPrivate::expandSelection(), QItemSelectionModelPrivate::finalize(), QItemSelectionModel::hasSelection(), QItemSelectionModel::rowIntersectsSelection(), QItemSelectionModel::select(), QItemSelectionModel::selectedIndexes(), QItemSelectionModel::selection(), and QListView::setSelection().

{
    if (other.isEmpty() ||
          !(command & QItemSelectionModel::Select ||
          command & QItemSelectionModel::Deselect ||
          command & QItemSelectionModel::Toggle))
        return;

    QItemSelection newSelection = other;
    // Collect intersections
    QItemSelection intersections;
    QItemSelection::iterator it = newSelection.begin();
    while (it != newSelection.end()) {
        if (!(*it).isValid()) {
            it = newSelection.erase(it);
            continue;
        }
        for (int t = 0; t < count(); ++t) {
            if ((*it).intersects(at(t)))
                intersections.append(at(t).intersected(*it));
        }
        ++it;
    }

    //  Split the old (and new) ranges using the intersections
    for (int i = 0; i < intersections.count(); ++i) { // for each intersection
        for (int t = 0; t < count();) { // splitt each old range
            if (at(t).intersects(intersections.at(i))) {
                split(at(t), intersections.at(i), this);
                removeAt(t);
            } else {
                ++t;
            }
        }
        // only split newSelection if Toggle is specified
        for (int n = 0; (command & QItemSelectionModel::Toggle) && n < newSelection.count();) {
            if (newSelection.at(n).intersects(intersections.at(i))) {
                split(newSelection.at(n), intersections.at(i), &newSelection);
                newSelection.removeAt(n);
            } else {
                ++n;
            }
        }
    }
    // do not add newSelection for Deselect
    if (!(command & QItemSelectionModel::Deselect))
        operator+=(newSelection);
}

select()

void QItemSelection::select	(	const QModelIndex &	topLeft,
		const QModelIndex &	bottomRight
	)

Adds the items in the range that extends from the top-left model item, specified by the topLeft index, to the bottom-right item, specified by bottomRight to the list.

Note

topLeft and bottomRight must have the same parent.

Definition at line 463 of file qitemselectionmodel.cpp.

Referenced by QListViewPrivate::selection(), and QListView::setSelection().

{
    if (!topLeft.isValid() || !bottomRight.isValid())
        return;

    if ((topLeft.model() != bottomRight.model())
        || topLeft.parent() != bottomRight.parent()) {
        qWarning("Can't select indexes from different model or with different parents");
        return;
    }
    if (topLeft.row() > bottomRight.row() || topLeft.column() > bottomRight.column()) {
        int top = qMin(topLeft.row(), bottomRight.row());
        int bottom = qMax(topLeft.row(), bottomRight.row());
        int left = qMin(topLeft.column(), bottomRight.column());
        int right = qMax(topLeft.column(), bottomRight.column());
        QModelIndex tl = topLeft.sibling(top, left);
        QModelIndex br = bottomRight.sibling(bottom, right);
        append(QItemSelectionRange(tl, br));
        return;
    }
    append(QItemSelectionRange(topLeft, bottomRight));
}

split()

void QItemSelection::split ( const QItemSelectionRange &  range, const QItemSelectionRange &  other, QItemSelection *  result  )

static

Splits the selection range using the selection other range.

Removes all items in other from range and puts the result in result. This can be compared with the semantics of the subtract operation of a set.

See also

merge()

Definition at line 581 of file qitemselectionmodel.cpp.

Referenced by QItemSelectionModelPrivate::_q_rowsAboutToBeRemoved(), and QItemSelectionModel::emitSelectionChanged().

{
    if (range.parent() != other.parent() || range.model() != other.model())
        return;

    QModelIndex parent = other.parent();
    int top = range.top();
    int left = range.left();
    int bottom = range.bottom();
    int right = range.right();
    int other_top = other.top();
    int other_left = other.left();
    int other_bottom = other.bottom();
    int other_right = other.right();
    const QAbstractItemModel *model = range.model();
    Q_ASSERT(model);
    if (other_top > top) {
        QModelIndex tl = model->index(top, left, parent);
        QModelIndex br = model->index(other_top - 1, right, parent);
        result->append(QItemSelectionRange(tl, br));
        top = other_top;
    }
    if (other_bottom < bottom) {
        QModelIndex tl = model->index(other_bottom + 1, left, parent);
        QModelIndex br = model->index(bottom, right, parent);
        result->append(QItemSelectionRange(tl, br));
        bottom = other_bottom;
    }
    if (other_left > left) {
        QModelIndex tl = model->index(top, left, parent);
        QModelIndex br = model->index(bottom, other_left - 1, parent);
        result->append(QItemSelectionRange(tl, br));
        left = other_left;
    }
    if (other_right < right) {
        QModelIndex tl = model->index(top, other_right + 1, parent);
        QModelIndex br = model->index(bottom, right, parent);
        result->append(QItemSelectionRange(tl, br));
        right = other_right;
    }
}

---

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

• /src/gui/itemviews/qitemselectionmodel.h
• /src/gui/itemviews/qitemselectionmodel.cpp