KSelectionProxyModel Class Reference

A Proxy Model which presents a subset of its source model to observers. More...

#include <kselectionproxymodel.h>

Inheritance diagram for KSelectionProxyModel:

[legend]

List of all members.

Public Types
enum	FilterBehavior {   SubTrees, SubTreeRoots, SubTreesWithoutRoots, ExactSelection,   ChildrenOfExactSelection }
Public Member Functions
	KSelectionProxyModel (QItemSelectionModel *selectionModel, QObject *parent=0)
virtual	~KSelectionProxyModel ()
virtual int	columnCount (const QModelIndex &=QModelIndex()) const
QVariant	data (const QModelIndex &index, int role=Qt::DisplayRole) const
virtual bool	dropMimeData (const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)
FilterBehavior	filterBehavior () const
virtual Qt::ItemFlags	flags (const QModelIndex &index) const
virtual bool	hasChildren (const QModelIndex &parent=QModelIndex()) const
virtual QVariant	headerData (int section, Qt::Orientation orientation, int role=Qt::DisplayRole) const
virtual QModelIndex	index (int, int, const QModelIndex &=QModelIndex()) const
QModelIndex	mapFromSource (const QModelIndex &sourceIndex) const
QModelIndex	mapToSource (const QModelIndex &proxyIndex) const
virtual QMimeData *	mimeData (const QModelIndexList &indexes) const
virtual QStringList	mimeTypes () const
virtual QModelIndex	parent (const QModelIndex &) const
virtual int	rowCount (const QModelIndex &parent=QModelIndex()) const
QItemSelectionModel *	selectionModel () const
void	setFilterBehavior (FilterBehavior behavior)
virtual void	setSourceModel (QAbstractItemModel *sourceModel)
virtual Qt::DropActions	supportedDropActions () const
Protected Member Functions
QList< QPersistentModelIndex >	sourceRootIndexes () const

---

Detailed Description

A Proxy Model which presents a subset of its source model to observers.

The KSelectionProxyModel is most useful as a convenience for displaying the selection in one view in another view. The selectionModel of the initial view is used to create a proxied model which is filtered based on

For example, when a user clicks a mail folder in one view in an email application, the contained emails should be displayed in another view.

This takes away the need for the developer to handle the selection between the views, including all the mapToSource, mapFromSource and setRootIndex calls.

  MyModel *sourceModel = new MyModel(this);
  QTreeView *leftView = new QTreeView(this);
  leftView->setModel(sourceModel);

  KSelectionProxyModel *selectionProxy = new KSelectionProxyModel(leftView->selectionModel(), this);

  QTreeView *rightView = new QTreeView(this);
  rightView->setModel(selectionProxy);

A Selection in one view creating a model for use with another view.

The KSelectionProxyModel can handle complex selections.

Non-contiguous selection creating a new simple model in a second view.

The contents of the secondary view depends on the selection in the primary view, and the configuration of the proxy model. See KSelectionProxyModel::setFilterBehavior for the different possible configurations.

For example, if the filterBehavior is SubTrees, selecting another item in an already selected subtree has no effect.

Selecting an item and its descendant.

See the test application in KDE/kdelibs/kdeui/tests/proxymodeltestapp to try out the valid configurations.

KSelectionProxyModel test application

Obviously, the KSelectionProxyModel may be used in a view, or further processed with other proxy models. See KAddressBook and AkonadiConsole in kdepim for examples which use a further KDescendantsProxyModel and QSortFilterProxyModel on top of a KSelectionProxyModel.

Additionally, this class can be used to programmatically choose some items from the source model to display in the view. For example, this is how the Favourite Folder View in KMail works, and is also used in unit testing.

See also: http://doc.trolltech.com/4.5/model-view-proxy-models.html

Since:

4.4

Author:

Stephen Kelly <steveire@gmail.com>

Definition at line 85 of file kselectionproxymodel.h.

---

Member Enumeration Documentation

enum KSelectionProxyModel::FilterBehavior

Enumerator:

SubTrees
SubTreeRoots
SubTreesWithoutRoots
ExactSelection
ChildrenOfExactSelection

Definition at line 109 of file kselectionproxymodel.h.

---

Constructor & Destructor Documentation

KSelectionProxyModel::KSelectionProxyModel	(	QItemSelectionModel *	selectionModel,
		QObject *	parent = 0
	)			[explicit]

ctor.

selectionModel The selection model used to filter what is presented by the proxy.

Definition at line 1153 of file kselectionproxymodel.cpp.

KSelectionProxyModel::~KSelectionProxyModel

(

)

[virtual]

dtor

Definition at line 1165 of file kselectionproxymodel.cpp.

---

Member Function Documentation

int KSelectionProxyModel::columnCount

(

const QModelIndex &

index = QModelIndex()

)

const [virtual]

Definition at line 1492 of file kselectionproxymodel.cpp.

QVariant KSelectionProxyModel::data	(	const QModelIndex &	index,
		int	role = Qt::DisplayRole
	)			const

Definition at line 1448 of file kselectionproxymodel.cpp.

bool KSelectionProxyModel::dropMimeData	(	const QMimeData *	data,
		Qt::DropAction	action,
		int	row,
		int	column,
		const QModelIndex &	parent
	)			[virtual]

Definition at line 1506 of file kselectionproxymodel.cpp.

KSelectionProxyModel::FilterBehavior KSelectionProxyModel::filterBehavior

(

)

const

Definition at line 1220 of file kselectionproxymodel.cpp.

Qt::ItemFlags KSelectionProxyModel::flags

(

const QModelIndex &

index

)

const [virtual]

Definition at line 1439 of file kselectionproxymodel.cpp.

bool KSelectionProxyModel::hasChildren

(

const QModelIndex &

parent = QModelIndex()

)

const [virtual]

Definition at line 1487 of file kselectionproxymodel.cpp.

QVariant KSelectionProxyModel::headerData	(	int	section,
		Qt::Orientation	orientation,
		int	role = Qt::DisplayRole
	)			const [virtual]

Definition at line 1461 of file kselectionproxymodel.cpp.

QModelIndex KSelectionProxyModel::index	(	int	row,
		int	column,
		const QModelIndex &	parent = QModelIndex()
	)			const [virtual]

Definition at line 1383 of file kselectionproxymodel.cpp.

QModelIndex KSelectionProxyModel::mapFromSource

(

const QModelIndex &

sourceIndex

)

const

Definition at line 1294 of file kselectionproxymodel.cpp.

QModelIndex KSelectionProxyModel::mapToSource

(

const QModelIndex &

proxyIndex

)

const

Definition at line 1281 of file kselectionproxymodel.cpp.

QMimeData * KSelectionProxyModel::mimeData

(

const QModelIndexList &

indexes

)

const [virtual]

Definition at line 1466 of file kselectionproxymodel.cpp.

QStringList KSelectionProxyModel::mimeTypes

(

)

const [virtual]

Definition at line 1475 of file kselectionproxymodel.cpp.

QModelIndex KSelectionProxyModel::parent

(

const QModelIndex &

index

)

const [virtual]

Definition at line 1419 of file kselectionproxymodel.cpp.

int KSelectionProxyModel::rowCount

(

const QModelIndex &

parent = QModelIndex()

)

const [virtual]

Definition at line 1344 of file kselectionproxymodel.cpp.

QItemSelectionModel * KSelectionProxyModel::selectionModel

(

)

const

Definition at line 1500 of file kselectionproxymodel.cpp.

void KSelectionProxyModel::setFilterBehavior

(

FilterBehavior

behavior

)

Set the filter behaviors of this model.

The filter behaviors of the model govern the content of the model based on the selection of the contained QItemSelectionModel.

See kdeui/proxymodeltestapp to try out the different proxy model behaviors.

The most useful behaviors are ExclusiveRoots, OnlySelected and OnlySelectedChildren.

The default behavior is ExclusiveRoots. This means that this proxy model will contain the roots of the items in the source model. Any descendants which are also selected have no additional effect. For example if the source model is like:

    (root)
      - A
      - B
        - C
        - D
          - E
            - F
          - G
      - H
      - I
        - J
        - K
        - L
    

And A, B and D are selected, the proxy will contain:

    (root)
      - A
      - B
        - C
        - D
          - E
            - F
          - G
    

That is, selecting 'D' or 'C' if 'B' is also selected has no effect. If 'B' is de-selected, then 'C' amd 'D' become top-level items:

    (root)
      - A
      - C
      - D
        - E
          - F
        - G
    

This is the behavior used by KJots when rendering books.

If the behavior is set to OmitChildren, then the children of selected indexes are not part of the model. If 'A', 'B' and 'D' are selected,

    (root)
      - A
      - B
    

Note that although 'D' is selected, it is not part of the proxy model, because its parent 'B' is already selected. In most cases this will be combined with IncludeAllSelected (see below).

OmitGrandChildren has the effect of showing the children of selected items, but not their grandchildren or further descendants. Again, if 'A', 'B', 'D' and 'E' are selected,

    (root)
      - A
      - B
        - C
        - D
    

Note that although 'E' is selected, it has no effect because its ancestor 'B' is also selected. (Keep reading :))

StartWithChildTrees has the effect of not making the selected items part of the model, but making their children part of the model instead. If 'A', 'B' and 'I' are selected:

    (root)
      - C
      - D
        - E
          - F
        - G
      - J
      - K
      - L
    

Note that 'A' has no children, so selecting it has no effect on the model. This can be used together with OmitGrandChildren to get the following effect with the same selection:

    (root)
      - C
      - D
      - J
      - K
      - L
    

Note that selecting 'E' in this behavior would have no effect because its ancestor 'B' is already in the model. The ChildrenOfSelected behavior is provided for convenience.

IncludeAllSelected has the effect of including all selected items in the tree even if an ancestor is already in the tree. This behavior can not be used on its own because it would cause duplicates in the proxy. It must be combined with either OmitGrandChildren or ChildrenOfSelected. The OnlySelected and OnlySelectedChildren behaviors are provide for convenience.

The OnlySelectedChildren has an effect similar to ChilrenOfSelected. The difference is that children of selected items appear in the model even if their children are already part of the model. For example, if 'A', 'B', 'D' and 'I' are selected:

    (root)
      - C
      - D
      - E
      - G
      - J
      - K
      - L
    

This would be useful for example if showing containers (for example maildirs) in one view and their items in another. Sub-maildirs would still appear in the proxy, but could be filtered out using a QSortfilterProxyModel.

The OnlySelected behavior causes the selected items to be part of the proxy model, even if their descendants are already selected, but children of selected items are not included.

Again, if 'A', 'B', 'D' and 'I' are selected:

    (root)
      - A
      - B
      - D
      - I
    

This is the behavior used by the Favourite Folder View in KMail.

Definition at line 1170 of file kselectionproxymodel.cpp.

void KSelectionProxyModel::setSourceModel

(

QAbstractItemModel *

sourceModel

)

[virtual]

reimp.

Reimplemented from QAbstractProxyModel.

Definition at line 1226 of file kselectionproxymodel.cpp.

QList< QPersistentModelIndex > KSelectionProxyModel::sourceRootIndexes

(

)

const [protected]

Definition at line 1529 of file kselectionproxymodel.cpp.

Qt::DropActions KSelectionProxyModel::supportedDropActions

(

)

const [virtual]

Definition at line 1481 of file kselectionproxymodel.cpp.

---

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

• kselectionproxymodel.h
• kselectionproxymodel.cpp