src/kitemviews/kitemmodelbase.h

   1 /*
   2  * SPDX-FileCopyrightText: 2011 Peter Penz <peter.penz19@gmail.com>
   3  *
   4  * Based on the Itemviews NG project from Trolltech Labs
   5  *
   6  * SPDX-License-Identifier: GPL-2.0-or-later
   7  */
   8
   9 #ifndef KITEMMODELBASE_H
  10 #define KITEMMODELBASE_H
  11
  12 #include "dolphin_export.h"
  13 #include "kitemviews/kitemrange.h"
  14 #include "kitemviews/kitemset.h"
  15
  16 #include <QHash>
  17 #include <QObject>
  18 #include <QUrl>
  19 #include <QVariant>
  20
  21 class QMimeData;
  22
  23 /**
  24  * @brief Base class for model implementations used by KItemListView and KItemListController.
  25  *
  26  * An item-model consists of a variable number of items. The number of items
  27  * is given by KItemModelBase::count(). The data of an item is accessed by a unique index
  28  * with KItemModelBase::data(). The indexes are integer-values counting from 0 to the
  29  * KItemModelBase::count() - 1.
  30  *
  31  * One item consists of a variable number of role/value-pairs.
  32  *
  33  * A model can optionally provide sorting- and grouping-capabilities.
  34  *
  35  * Also optionally it is possible to provide a tree of items by implementing the methods
  36  * setExpanded(), isExpanded(), isExpandable() and expandedParentsCount().
  37  */
  38 class DOLPHIN_EXPORT KItemModelBase : public QObject
  39 {
  40     Q_OBJECT
  41
  42 public:
  43     explicit KItemModelBase(QObject* parent = nullptr);
  44     explicit KItemModelBase(const QByteArray& sortRole, QObject* parent = nullptr);
  45     ~KItemModelBase() override;
  46
  47     /** @return The number of items. */
  48     virtual int count() const = 0;
  49
  50     virtual QHash<QByteArray, QVariant> data(int index) const = 0;
  51
  52     /**
  53      * Sets the data for the item at \a index to the given \a values. Returns true
  54      * if the data was set on the item; returns false otherwise.
  55      *
  56      * The default implementation does not set the data, and will always return
  57      * false.
  58      */
  59     virtual bool setData(int index, const QHash<QByteArray, QVariant>& values);
  60
  61     /**
  62      * Enables/disables the grouped sorting. The method KItemModelBase::onGroupedSortingChanged() will be
  63      * called so that model-implementations can react on the grouped-sorting change. Afterwards the
  64      * signal groupedSortingChanged() will be emitted. If the grouped sorting is enabled, the method
  65      * KItemModelBase::groups() must be implemented.
  66      */
  67     void setGroupedSorting(bool grouped);
  68     bool groupedSorting() const;
  69
  70     /**
  71      * Sets the sort-role to \a role. The method KItemModelBase::onSortRoleChanged() will be
  72      * called so that model-implementations can react on the sort-role change. Afterwards the
  73      * signal sortRoleChanged() will be emitted.
  74      * The implementation should resort only if \a resortItems is true.
  75      */
  76     void setSortRole(const QByteArray& role, bool resortItems = true);
  77     QByteArray sortRole() const;
  78
  79     /**
  80      * Sets the sort order to \a order. The method KItemModelBase::onSortOrderChanged() will be
  81      * called so that model-implementations can react on the sort order change. Afterwards the
  82      * signal sortOrderChanged() will be emitted.
  83      */
  84     void setSortOrder(Qt::SortOrder order);
  85     Qt::SortOrder sortOrder() const;
  86
  87     /**
  88      * @return Translated description for the \p role. The description is e.g. used
  89      *         for the header in KItemListView.
  90      */
  91     virtual QString roleDescription(const QByteArray& role) const;
  92
  93     /**
  94      * @return List of group headers. Each list-item consists of the index of the item
  95      *         that represents the first item of a group and a value represented
  96      *         as QVariant. The value is shown by an instance of KItemListGroupHeader.
  97      *         Per default an empty list is returned.
  98      */
  99     virtual QList<QPair<int, QVariant> > groups() const;
 100
 101     /**
 102      * Expands the item with the index \a index if \a expanded is true.
 103      * If \a expanded is false the item will be collapsed.
 104      *
 105      * Per default no expanding of items is implemented. When implementing
 106      * this method it is mandatory to overwrite KItemModelBase::isExpandable()
 107      * and KItemListView::supportsExpandableItems() to return true.
 108      *
 109      * @return True if the operation has been successful.
 110      */
 111     virtual bool setExpanded(int index, bool expanded);
 112
 113     /**
 114      * @return True if the item with the index \a index is expanded.
 115      *         Per default no expanding of items is implemented. When implementing
 116      *         this method it is mandatory to overwrite KItemModelBase::isExpandable()
 117      *         and KItemListView::supportsExpandableItems() to return true.
 118      */
 119     virtual bool isExpanded(int index) const;
 120
 121     /**
 122      * @return True if expanding and collapsing of the item with the index \a index
 123      *         is supported. Per default false is returned.
 124      */
 125     virtual bool isExpandable(int index) const;
 126
 127     /**
 128      * @return Number of expanded parent items for the item with the given index.
 129      *         Per default 0 is returned.
 130      */
 131     virtual int expandedParentsCount(int index) const;
 132
 133     /**
 134      * @return MIME-data for the items given by \a indexes. The default implementation
 135      *         returns 0. The ownership of the returned instance is in the hand of the
 136      *         caller of this method. The method must be implemented if dragging of
 137      *         items should be possible.
 138      */
 139     virtual QMimeData* createMimeData(const KItemSet& indexes) const;
 140
 141     /**
 142      * @return Reimplement this to return the index for the first item
 143      * beginning with string typed in through the keyboard, -1 if not found.
 144      * @param text              the text which has been typed in through the keyboard
 145      * @param startFromIndex    the index from which to start searching from
 146      */
 147     virtual int indexForKeyboardSearch(const QString& text, int startFromIndex = 0) const;
 148
 149     /**
 150      * @return True, if the item with the index \a index basically supports dropping.
 151      *         Per default false is returned.
 152      *
 153      *         The information is used only to give a visual feedback during a drag operation
 154      *         and not to decide whether a drop event gets emitted. It is it is still up to
 155      *         the receiver of KItemListController::itemDropEvent() to decide how to handle
 156      *         the drop event.
 157      */
 158     // TODO: Should the MIME-data be passed too so that the model can do a more specific
 159     // decision whether it accepts the drop?
 160     virtual bool supportsDropping(int index) const;
 161
 162     /**
 163      * @return An internal mimetype to signal that an itemDropEvent() should be rejected by
 164      *         the receiving model.
 165      *
 166      *         This mimeType can be used in createMimeData() to notify that the
 167      *         drop-onto-items events should be ignored, while the drop-between-items
 168      *         ones should be still accepted.
 169      */
 170     QString blacklistItemDropEventMimeType() const;
 171
 172     /**
 173      * @return URL of the item at the specified index
 174      */
 175     virtual QUrl url(int index) const;
 176
 177     /**
 178      * @return True, if item at specified index is a directory
 179      */
 180     virtual bool isDir(int index) const;
 181
 182     /**
 183      * @return Parent directory of the items that are shown
 184      */
 185     virtual QUrl directory() const;
 186 Q_SIGNALS:
 187     /**
 188      * Is emitted if one or more items have been inserted. Each item-range consists
 189      * of:
 190      * - an index where items have been inserted
 191      * - the number of inserted items.
 192      * The index of each item-range represents the index of the model
 193      * before the items have been inserted.
 194      *
 195      * For the item-ranges it is assured that:
 196      * - They don't overlap
 197      * - The index of item-range n is smaller than the index of item-range n + 1.
 198      */
 199     void itemsInserted(const KItemRangeList& itemRanges);
 200
 201     /**
 202      * Is emitted if one or more items have been removed. Each item-range consists
 203      * of:
 204      * - an index where items have been inserted
 205      * - the number of inserted items.
 206      * The index of each item-range represents the index of the model
 207      * before the items have been removed.
 208      *
 209      * For the item-ranges it is assured that:
 210      * - They don't overlap
 211      * - The index of item-range n is smaller than the index of item-range n + 1.
 212      */
 213     void itemsRemoved(const KItemRangeList& itemRanges);
 214
 215     /**
 216      * Is emitted if one ore more items get moved.
 217      * @param itemRange      Item-range that gets moved to a new position.
 218      * @param movedToIndexes New positions for each element of the item-range.
 219      *
 220      * For example if the model has 10 items and the items 0 and 1 get exchanged
 221      * with the items 5 and 6 then the parameters look like this:
 222      * - itemRange: has the index 0 and a count of 7.
 223      * - movedToIndexes: Contains the seven values 5, 6, 2, 3, 4, 0, 1
 224      *
 225      * This signal implies that the groups might have changed. Therefore,
 226      * gropusChanged() is not emitted if this signal is emitted.
 227      */
 228     void itemsMoved(const KItemRange& itemRange, const QList<int>& movedToIndexes);
 229
 230     void itemsChanged(const KItemRangeList& itemRanges, const QSet<QByteArray>& roles);
 231
 232     /**
 233      * Is emitted if the groups have changed, even though the order of the
 234      * items has not been modified.
 235      */
 236     void groupsChanged();
 237
 238     void groupedSortingChanged(bool current);
 239     void sortRoleChanged(const QByteArray& current, const QByteArray& previous);
 240     void sortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous);
 241
 242 protected:
 243     /**
 244      * Is invoked if the grouped sorting has been changed by KItemModelBase::setGroupedSorting(). Allows
 245      * to react on the changed grouped sorting  before the signal groupedSortingChanged() will be emitted.
 246      */
 247     virtual void onGroupedSortingChanged(bool current);
 248
 249     /**
 250      * Is invoked if the sort role has been changed by KItemModelBase::setSortRole(). Allows
 251      * to react on the changed sort role before the signal sortRoleChanged() will be emitted.
 252      * The implementation must assure that the items are sorted by the role given by \a current.
 253      * Usually the most efficient way is to emit a
 254      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 255      * itemsInserted() signal afterwards.
 256      * The implementation should resort only if \a resortItems is true.
 257      */
 258     virtual void onSortRoleChanged(const QByteArray& current, const QByteArray& previous, bool resortItems = true);
 259
 260     /**
 261      * Is invoked if the sort order has been changed by KItemModelBase::setSortOrder(). Allows
 262      * to react on the changed sort order before the signal sortOrderChanged() will be emitted.
 263      * The implementation must assure that the items are sorted by the order given by \a current.
 264      * Usually the most efficient way is to emit a
 265      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 266      * itemsInserted() signal afterwards.
 267      */
 268     virtual void onSortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous);
 269
 270 private:
 271     bool m_groupedSorting;
 272     QByteArray m_sortRole;
 273     Qt::SortOrder m_sortOrder;
 274 };
 275
 276 inline Qt::SortOrder KItemModelBase::sortOrder() const
 277 {
 278     return m_sortOrder;
 279 }
 280
 281 #endif
 282
 283