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 True, if the item with the index \a index can be entered in during hover actions.
 164      *         Per default false is returned.
 165      *
 166      *         This is used to check that if the item
 167      *         we're hovering on is either directory or a desktop file.
 168      */
 169     virtual bool canEnterOnHover(int index) const;
 170
 171     /**
 172      * @return An internal mimetype to signal that an itemDropEvent() should be rejected by
 173      *         the receiving model.
 174      *
 175      *         This mimeType can be used in createMimeData() to notify that the
 176      *         drop-onto-items events should be ignored, while the drop-between-items
 177      *         ones should be still accepted.
 178      */
 179     QString blacklistItemDropEventMimeType() const;
 180
 181     /**
 182      * @return URL of the item at the specified index
 183      */
 184     virtual QUrl url(int index) const;
 185
 186     /**
 187      * @return True, if item at specified index is a directory
 188      */
 189     virtual bool isDir(int index) const;
 190
 191     /**
 192      * @return Parent directory of the items that are shown
 193      */
 194     virtual QUrl directory() const;
 195 Q_SIGNALS:
 196     /**
 197      * Is emitted if one or more items have been inserted. Each item-range consists
 198      * of:
 199      * - an index where items have been inserted
 200      * - the number of inserted items.
 201      * The index of each item-range represents the index of the model
 202      * before the items have been inserted.
 203      *
 204      * For the item-ranges it is assured that:
 205      * - They don't overlap
 206      * - The index of item-range n is smaller than the index of item-range n + 1.
 207      */
 208     void itemsInserted(const KItemRangeList &itemRanges);
 209
 210     /**
 211      * Is emitted if one or more items have been removed. Each item-range consists
 212      * of:
 213      * - an index where items have been inserted
 214      * - the number of inserted items.
 215      * The index of each item-range represents the index of the model
 216      * before the items have been removed.
 217      *
 218      * For the item-ranges it is assured that:
 219      * - They don't overlap
 220      * - The index of item-range n is smaller than the index of item-range n + 1.
 221      */
 222     void itemsRemoved(const KItemRangeList &itemRanges);
 223
 224     /**
 225      * Is emitted if one ore more items get moved.
 226      * @param itemRange      Item-range that gets moved to a new position.
 227      * @param movedToIndexes New positions for each element of the item-range.
 228      *
 229      * For example if the model has 10 items and the items 0 and 1 get exchanged
 230      * with the items 5 and 6 then the parameters look like this:
 231      * - itemRange: has the index 0 and a count of 7.
 232      * - movedToIndexes: Contains the seven values 5, 6, 2, 3, 4, 0, 1
 233      *
 234      * This signal implies that the groups might have changed. Therefore,
 235      * gropusChanged() is not emitted if this signal is emitted.
 236      */
 237     void itemsMoved(const KItemRange &itemRange, const QList<int> &movedToIndexes);
 238
 239     void itemsChanged(const KItemRangeList &itemRanges, const QSet<QByteArray> &roles);
 240
 241     /**
 242      * Is emitted if the groups have changed, even though the order of the
 243      * items has not been modified.
 244      */
 245     void groupsChanged();
 246
 247     void groupedSortingChanged(bool current);
 248     void sortRoleChanged(const QByteArray &current, const QByteArray &previous);
 249     void sortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous);
 250
 251 protected:
 252     /**
 253      * Is invoked if the grouped sorting has been changed by KItemModelBase::setGroupedSorting(). Allows
 254      * to react on the changed grouped sorting  before the signal groupedSortingChanged() will be emitted.
 255      */
 256     virtual void onGroupedSortingChanged(bool current);
 257
 258     /**
 259      * Is invoked if the sort role has been changed by KItemModelBase::setSortRole(). Allows
 260      * to react on the changed sort role before the signal sortRoleChanged() will be emitted.
 261      * The implementation must assure that the items are sorted by the role given by \a current.
 262      * Usually the most efficient way is to emit a
 263      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 264      * itemsInserted() signal afterwards.
 265      * The implementation should resort only if \a resortItems is true.
 266      */
 267     virtual void onSortRoleChanged(const QByteArray &current, const QByteArray &previous, bool resortItems = true);
 268
 269     /**
 270      * Is invoked if the sort order has been changed by KItemModelBase::setSortOrder(). Allows
 271      * to react on the changed sort order before the signal sortOrderChanged() will be emitted.
 272      * The implementation must assure that the items are sorted by the order given by \a current.
 273      * Usually the most efficient way is to emit a
 274      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 275      * itemsInserted() signal afterwards.
 276      */
 277     virtual void onSortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous);
 278
 279 private:
 280     bool m_groupedSorting;
 281     QByteArray m_sortRole;
 282     Qt::SortOrder m_sortOrder;
 283 };
 284
 285 inline Qt::SortOrder KItemModelBase::sortOrder() const
 286 {
 287     return m_sortOrder;
 288 }
 289
 290 #endif