1/*
2 Copyright (C) 2010 Klarälvdalens Datakonsult AB,
3 a KDAB Group company, info@kdab.net,
4 author Stephen Kelly <stephen@kdab.com>
5
6 This library is free software; you can redistribute it and/or modify it
7 under the terms of the GNU Library General Public License as published by
8 the Free Software Foundation; either version 2 of the License, or (at your
9 option) any later version.
10
11 This library is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
14 License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301, USA.
20*/
21
22#ifndef KBREADCRUMBSPROXYMODEL_H
23#define KBREADCRUMBSPROXYMODEL_H
24
25#include <QtGui/QItemSelectionModel>
26#include <QtCore/QAbstractItemModel>
27
28#include "kdeui_export.h"
29
30class KBreadcrumbSelectionModelPrivate;
31
32/**
33 @class KBreadcrumbSelectionModel kbreadcrumbselectionmodel.h
34
35 @brief Selects the parents of selected items to create breadcrumbs
36
37 For example, if the tree is
38 @verbatim
39 - A
40 - B
41 - - C
42 - - D
43 - - - E
44 - - - - F
45 @endverbatim
46
47 and E is selected, the selection can contain
48
49 @verbatim
50 - B
51 - D
52 @endverbatim
53
54 or
55
56 @verbatim
57 - B
58 - D
59 - E
60 @endverbatim
61
62 if isActualSelectionIncluded is true.
63
64 The depth of the selection may also be set. For example if the breadcrumbLength is 1:
65
66 @verbatim
67 - D
68 - E
69 @endverbatim
70
71 And if breadcrumbLength is 2:
72
73 @verbatim
74 - B
75 - D
76 - E
77 @endverbatim
78
79 A KBreadcrumbsProxyModel with a breadcrumbLength of 0 and including the actual selection is
80 the same as a KSelectionProxyModel in the KSelectionProxyModel::ExactSelection configuration.
81
82 @code
83 view1->setModel(rootModel);
84
85 QItemSelectionModel *breadcrumbSelectionModel = new QItemSelectionModel(rootModel, this);
86
87 KBreadcrumbSelectionModel *breadcrumbProxySelector = new KBreadcrumbSelectionModel(breadcrumbSelectionModel, rootModel, this);
88
89 view1->setSelectionModel(breadcrumbProxySelector);
90
91 KSelectionProxyModel *breadcrumbSelectionProxyModel = new KSelectionProxyModel( breadcrumbSelectionModel, this);
92 breadcrumbSelectionProxyModel->setSourceModel( rootModel );
93 breadcrumbSelectionProxyModel->setFilterBehavior( KSelectionProxyModel::ExactSelection );
94
95 view2->setModel(breadcrumbSelectionProxyModel);
96 @endcode
97
98 @image html kbreadcrumbselectionmodel.png "KBreadcrumbSelectionModel in several configurations"
99
100 This can work in two directions. One option is for a single selection in the KBreadcrumbSelectionModel to invoke
101 the breadcrumb selection in its constructor argument.
102
103 The other is for a selection in the itemselectionmodel in the constructor argument to cause a breadcrumb selection
104 in @p this.
105
106 @since 4.5
107
108*/
109class KDEUI_EXPORT KBreadcrumbSelectionModel : public QItemSelectionModel
110{
111 Q_OBJECT
112public:
113 enum BreadcrumbTarget
114 {
115 MakeBreadcrumbSelectionInOther,
116 MakeBreadcrumbSelectionInSelf
117 };
118
119 explicit KBreadcrumbSelectionModel(QItemSelectionModel *selectionModel, QObject* parent = 0);
120 KBreadcrumbSelectionModel(QItemSelectionModel *selectionModel, BreadcrumbTarget target, QObject* parent = 0);
121 virtual ~KBreadcrumbSelectionModel();
122
123 /**
124 Returns whether the actual selection in included in the proxy.
125
126 The default is true.
127 */
128 bool isActualSelectionIncluded() const;
129
130 /**
131 Set whether the actual selection in included in the proxy to @p isActualSelectionIncluded.
132 */
133 void setActualSelectionIncluded(bool isActualSelectionIncluded);
134
135 /**
136 Returns the depth that the breadcrumb selection should go to.
137 */
138 int breadcrumbLength() const;
139
140 /**
141 Sets the depth that the breadcrumb selection should go to.
142
143 If the @p breadcrumbLength is -1, all breadcrumbs are selected.
144 The default is -1
145 */
146 void setBreadcrumbLength(int breadcrumbLength);
147
148 /* reimp */ void select(const QModelIndex &index, QItemSelectionModel::SelectionFlags command);
149
150 /* reimp */ void select(const QItemSelection &selection, QItemSelectionModel::SelectionFlags command);
151
152protected:
153 KBreadcrumbSelectionModelPrivate * const d_ptr;
154private:
155 //@cond PRIVATE
156 Q_DECLARE_PRIVATE(KBreadcrumbSelectionModel)
157 Q_PRIVATE_SLOT( d_func(),void sourceSelectionChanged(const QItemSelection &selected, const QItemSelection &deselected))
158 Q_PRIVATE_SLOT( d_func(),void syncBreadcrumbs())
159 //@cond PRIVATE
160};
161
162
163#endif
164