File indexing completed on 2024-07-21 06:38:21

0001 /*
0002     SPDX-FileCopyrightText: 2010 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>
0003     SPDX-FileContributor: Stephen Kelly <stephen@kdab.com>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KBREADCRUMBSELECTIONMODEL_H
0009 #define KBREADCRUMBSELECTIONMODEL_H
0010 
0011 #include <QItemSelectionModel>
0012 
0013 #include "kitemmodels_export.h"
0014 
0015 #include <memory>
0016 
0017 class KBreadcrumbSelectionModelPrivate;
0018 
0019 /**
0020   @class KBreadcrumbSelectionModel kbreadcrumbselectionmodel.h KBreadcrumbSelectionModel
0021 
0022   @brief Selects the parents of selected items to create breadcrumbs
0023 
0024   For example, if the tree is
0025   @verbatim
0026     - A
0027     - B
0028     - - C
0029     - - D
0030     - - - E
0031     - - - - F
0032   @endverbatim
0033 
0034   and E is selected, the selection can contain
0035 
0036   @verbatim
0037     - B
0038     - D
0039   @endverbatim
0040 
0041   or
0042 
0043   @verbatim
0044     - B
0045     - D
0046     - E
0047   @endverbatim
0048 
0049   if isActualSelectionIncluded is true.
0050 
0051   The depth of the selection may also be set. For example if the breadcrumbLength is 1:
0052 
0053   @verbatim
0054     - D
0055     - E
0056   @endverbatim
0057 
0058   And if breadcrumbLength is 2:
0059 
0060   @verbatim
0061     - B
0062     - D
0063     - E
0064   @endverbatim
0065 
0066   A KBreadcrumbsSelectionModel with a breadcrumbLength of 0 and including the actual selection is
0067   the same as a KSelectionProxyModel in the KSelectionProxyModel::ExactSelection configuration.
0068 
0069   @code
0070     view1->setModel(rootModel);
0071 
0072     QItemSelectionModel *breadcrumbSelectionModel = new QItemSelectionModel(rootModel, this);
0073 
0074     KBreadcrumbSelectionModel *breadcrumbProxySelector = new KBreadcrumbSelectionModel(breadcrumbSelectionModel, rootModel, this);
0075 
0076     view1->setSelectionModel(breadcrumbProxySelector);
0077 
0078     KSelectionProxyModel *breadcrumbSelectionProxyModel = new KSelectionProxyModel( breadcrumbSelectionModel, this);
0079     breadcrumbSelectionProxyModel->setSourceModel( rootModel );
0080     breadcrumbSelectionProxyModel->setFilterBehavior( KSelectionProxyModel::ExactSelection );
0081 
0082     view2->setModel(breadcrumbSelectionProxyModel);
0083   @endcode
0084 
0085   @image html kbreadcrumbselectionmodel.png "KBreadcrumbSelectionModel in several configurations"
0086 
0087   This can work in two directions. One option is for a single selection in the KBreadcrumbSelectionModel to invoke
0088   the breadcrumb selection in its constructor argument.
0089 
0090   The other is for a selection in the itemselectionmodel in the constructor argument to cause a breadcrumb selection
0091   in @p this.
0092 
0093   @since 4.5
0094 
0095 */
0096 class KITEMMODELS_EXPORT KBreadcrumbSelectionModel : public QItemSelectionModel
0097 {
0098     Q_OBJECT
0099 public:
0100     enum BreadcrumbTarget {
0101         MakeBreadcrumbSelectionInOther,
0102         MakeBreadcrumbSelectionInSelf,
0103     };
0104 
0105     explicit KBreadcrumbSelectionModel(QItemSelectionModel *selectionModel, QObject *parent = nullptr);
0106     KBreadcrumbSelectionModel(QItemSelectionModel *selectionModel, BreadcrumbTarget target, QObject *parent = nullptr);
0107     ~KBreadcrumbSelectionModel() override;
0108 
0109     /**
0110       Returns whether the actual selection in included in the proxy.
0111 
0112       The default is true.
0113     */
0114     bool isActualSelectionIncluded() const;
0115 
0116     /**
0117       Set whether the actual selection in included in the proxy to @p isActualSelectionIncluded.
0118     */
0119     void setActualSelectionIncluded(bool isActualSelectionIncluded);
0120 
0121     /**
0122       Returns the depth that the breadcrumb selection should go to.
0123     */
0124     int breadcrumbLength() const;
0125 
0126     /**
0127       Sets the depth that the breadcrumb selection should go to.
0128 
0129       If the @p breadcrumbLength is -1, all breadcrumbs are selected.
0130       The default is -1
0131     */
0132     void setBreadcrumbLength(int breadcrumbLength);
0133 
0134     void select(const QModelIndex &index, QItemSelectionModel::SelectionFlags command) override;
0135 
0136     void select(const QItemSelection &selection, QItemSelectionModel::SelectionFlags command) override;
0137 
0138 protected:
0139     std::unique_ptr<KBreadcrumbSelectionModelPrivate> const d_ptr;
0140 
0141 private:
0142     //@cond PRIVATE
0143     Q_DECLARE_PRIVATE(KBreadcrumbSelectionModel)
0144     //@cond PRIVATE
0145 };
0146 
0147 #endif