1/*
2 Copyright (c) 2009 Stephen Kelly <steveire@gmail.com>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_SELECTIONPROXYMODEL_H
21#define AKONADI_SELECTIONPROXYMODEL_H
22
23#include <kselectionproxymodel.h>
24
25#include "akonadi_export.h"
26
27namespace Akonadi
28{
29
30class SelectionProxyModelPrivate;
31
32/**
33 * @short A proxy model used to reference count selected Akonadi::Collection in a view
34 *
35 * Only selected Collections will be populated and monitored for changes. Unselected
36 * Collections will be ignored.
37 *
38 * This model extends KSelectionProxyModel to implement reference counting on the Collections
39 * in an EntityTreeModel. The EntityTreeModel must use LazyPopulation to enable
40 * SelectionProxyModel to work.
41 *
42 * By selecting a Collection, its reference count will be increased. A Collection in the
43 * EntityTreeModel which has a reference count of zero will ignore all signals from Monitor
44 * about items changed, inserted, removed etc, which can be expensive operations.
45 *
46 * Example:
47 *
48 * @code
49 *
50 * using namespace Akonadi;
51 *
52 * // itemView
53 * // ^
54 * // |
55 * // itemModel
56 * // |
57 * // flatModel
58 * // |
59 * // collectionView --> selectionModel
60 * // ^ ^
61 * // | |
62 * // collectionFilter |
63 * // \______________model
64 *
65 * EntityTreeModel *model = new EntityTreeModel( ... );
66 *
67 * // setup collection model
68 * EntityMimeTypeFilterModel *collectionFilter = new EntityMimeTypeFilterModel( this );
69 * collectionFilter->setSourceModel( model );
70 * collectionFilter->addMimeTypeInclusionFilter( Collection::mimeType() );
71 * collectionFilter->setHeaderGroup( EntityTreeModel::CollectionTreeHeaders );
72 *
73 * // setup collection view
74 * EntityTreeView *collectionView = new EntityTreeView( this );
75 * collectionView->setModel( collectionFilter );
76 *
77 * // setup selection model
78 * SelectionProxyModel *selectionModel = new SelectionProxyModel( collectionView->selectionModel(), this );
79 * selectionModel->setSourceModel( model );
80 *
81 * // setup item model
82 * KDescendantsProxyModel *flatModel = new KDescendantsProxyModel( this );
83 * flatModel->setSourceModel( selectionModel );
84 *
85 * EntityMimeTypeFilterModel *itemModel = new EntityMimeTypeFilterModel( this );
86 * itemModel->setSourceModel( flatModel );
87 * itemModel->setHeaderGroup( EntityTreeModel::ItemListHeaders );
88 * itemModel->addMimeTypeExclusionFilter( Collection::mimeType() );
89 *
90 * EntityListView *itemView = new EntityListView( this );
91 * itemView->setModel( itemModel );
92 * @endcode
93 *
94 * See \ref libakonadi_integration "Integration in your Application" for further guidance on the use of this class.
95
96 * @author Stephen Kelly <steveire@gmail.com>
97 * @since 4.4
98 */
99class AKONADI_EXPORT SelectionProxyModel : public KSelectionProxyModel
100{
101 Q_OBJECT
102
103public:
104 /**
105 * Creates a new selection proxy model.
106 *
107 * @param selectionModel The selection model of the source view.
108 * @param parent The parent object.
109 */
110 explicit SelectionProxyModel(QItemSelectionModel *selectionModel, QObject *parent = 0);
111 ~SelectionProxyModel();
112
113private:
114 //@cond PRIVATE
115 Q_DECLARE_PRIVATE(SelectionProxyModel)
116 SelectionProxyModelPrivate *const d_ptr;
117
118 Q_PRIVATE_SLOT(d_func(), void rootIndexAdded(const QModelIndex &))
119 Q_PRIVATE_SLOT(d_func(), void rootIndexAboutToBeRemoved(const QModelIndex &))
120 //@endcond
121};
122
123}
124
125#endif
126