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, const QByteArray &groupRole, 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, bool resortItems = true);
  85     Qt::SortOrder sortOrder() const;
  86
  87     /**
  88      * Sets the group-role to \a role. The method KItemModelBase::onGroupRoleChanged() will be
  89      * called so that model-implementations can react on the group-role change. Afterwards the
  90      * signal groupRoleChanged() will be emitted.
  91      * The implementation should regroup only if \a regroupItems is true.
  92      */
  93     void setGroupRole(const QByteArray &role, bool regroupItems = true);
  94     QByteArray groupRole() const;
  95
  96     /**
  97      * Sets the group order to \a order. The method KItemModelBase::onGroupOrderChanged() will be
  98      * called so that model-implementations can react on the group order change. Afterwards the
  99      * signal groupOrderChanged() will be emitted.
 100      */
 101     void setGroupOrder(Qt::SortOrder order, bool resortItems = true);
 102     Qt::SortOrder groupOrder() const;
 103
 104     /**
 105      * @return Translated description for the \p role. The description is e.g. used
 106      *         for the header in KItemListView.
 107      */
 108     virtual QString roleDescription(const QByteArray &role) const;
 109
 110     /**
 111      * @return List of group headers. Each list-item consists of the index of the item
 112      *         that represents the first item of a group and a value represented
 113      *         as QVariant. The value is shown by an instance of KItemListGroupHeader.
 114      *         Per default an empty list is returned.
 115      */
 116     virtual QList<QPair<int, QVariant>> groups() const;
 117
 118     /**
 119      * Expands the item with the index \a index if \a expanded is true.
 120      * If \a expanded is false the item will be collapsed.
 121      *
 122      * Per default no expanding of items is implemented. When implementing
 123      * this method it is mandatory to overwrite KItemModelBase::isExpandable()
 124      * and KItemListView::supportsExpandableItems() to return true.
 125      *
 126      * @return True if the operation has been successful.
 127      */
 128     virtual bool setExpanded(int index, bool expanded);
 129
 130     /**
 131      * @return True if the item with the index \a index is expanded.
 132      *         Per default no expanding of items is implemented. When implementing
 133      *         this method it is mandatory to overwrite KItemModelBase::isExpandable()
 134      *         and KItemListView::supportsExpandableItems() to return true.
 135      */
 136     virtual bool isExpanded(int index) const;
 137
 138     /**
 139      * @return True if expanding and collapsing of the item with the index \a index
 140      *         is supported. Per default false is returned.
 141      */
 142     virtual bool isExpandable(int index) const;
 143
 144     /**
 145      * @return Number of expanded parent items for the item with the given index.
 146      *         Per default 0 is returned.
 147      */
 148     virtual int expandedParentsCount(int index) const;
 149
 150     /**
 151      * @return MIME-data for the items given by \a indexes. The default implementation
 152      *         returns 0. The ownership of the returned instance is in the hand of the
 153      *         caller of this method. The method must be implemented if dragging of
 154      *         items should be possible.
 155      */
 156     virtual QMimeData *createMimeData(const KItemSet &indexes) const;
 157
 158     /**
 159      * @return Reimplement this to return the index for the first item
 160      * beginning with string typed in through the keyboard, -1 if not found.
 161      * @param text              the text which has been typed in through the keyboard
 162      * @param startFromIndex    the index from which to start searching from
 163      */
 164     virtual int indexForKeyboardSearch(const QString &text, int startFromIndex = 0) const;
 165
 166     /**
 167      * @return True, if the item with the index \a index basically supports dropping.
 168      *         Per default false is returned.
 169      *
 170      *         The information is used only to give a visual feedback during a drag operation
 171      *         and not to decide whether a drop event gets emitted. It is it is still up to
 172      *         the receiver of KItemListController::itemDropEvent() to decide how to handle
 173      *         the drop event.
 174      */
 175     // TODO: Should the MIME-data be passed too so that the model can do a more specific
 176     // decision whether it accepts the drop?
 177     virtual bool supportsDropping(int index) const;
 178
 179     /**
 180      * @return True, if the item with the index \a index can be entered in during hover actions.
 181      *         Per default false is returned.
 182      *
 183      *         This is used to check that if the item
 184      *         we're hovering on is either directory or a desktop file.
 185      */
 186     virtual bool canEnterOnHover(int index) const;
 187
 188     /**
 189      * @return An internal mimetype to signal that an itemDropEvent() should be rejected by
 190      *         the receiving model.
 191      *
 192      *         This mimeType can be used in createMimeData() to notify that the
 193      *         drop-onto-items events should be ignored, while the drop-between-items
 194      *         ones should be still accepted.
 195      */
 196     QString blacklistItemDropEventMimeType() const;
 197
 198     /**
 199      * @return URL of the item at the specified index
 200      */
 201     virtual QUrl url(int index) const;
 202
 203     /**
 204      * @return True, if item at specified index is a directory
 205      */
 206     virtual bool isDir(int index) const;
 207
 208     /**
 209      * @return Parent directory of the items that are shown
 210      */
 211     virtual QUrl directory() const;
 212 Q_SIGNALS:
 213     /**
 214      * Is emitted if one or more items have been inserted. Each item-range consists
 215      * of:
 216      * - an index where items have been inserted
 217      * - the number of inserted items.
 218      * The index of each item-range represents the index of the model
 219      * before the items have been inserted.
 220      *
 221      * For the item-ranges it is assured that:
 222      * - They don't overlap
 223      * - The index of item-range n is smaller than the index of item-range n + 1.
 224      */
 225     void itemsInserted(const KItemRangeList &itemRanges);
 226
 227     /**
 228      * Is emitted if one or more items have been removed. Each item-range consists
 229      * of:
 230      * - an index where items have been inserted
 231      * - the number of inserted items.
 232      * The index of each item-range represents the index of the model
 233      * before the items have been removed.
 234      *
 235      * For the item-ranges it is assured that:
 236      * - They don't overlap
 237      * - The index of item-range n is smaller than the index of item-range n + 1.
 238      */
 239     void itemsRemoved(const KItemRangeList &itemRanges);
 240
 241     /**
 242      * Is emitted if one ore more items get moved.
 243      * @param itemRange      Item-range that gets moved to a new position.
 244      * @param movedToIndexes New positions for each element of the item-range.
 245      *
 246      * For example if the model has 10 items and the items 0 and 1 get exchanged
 247      * with the items 5 and 6 then the parameters look like this:
 248      * - itemRange: has the index 0 and a count of 7.
 249      * - movedToIndexes: Contains the seven values 5, 6, 2, 3, 4, 0, 1
 250      *
 251      * This signal implies that the groups might have changed. Therefore,
 252      * gropusChanged() is not emitted if this signal is emitted.
 253      */
 254     void itemsMoved(const KItemRange &itemRange, const QList<int> &movedToIndexes);
 255
 256     void itemsChanged(const KItemRangeList &itemRanges, const QSet<QByteArray> &roles);
 257
 258     /**
 259      * Is emitted if the groups have changed, even though the order of the
 260      * items has not been modified.
 261      */
 262     void groupsChanged();
 263
 264     void groupedSortingChanged(bool current);
 265     void sortRoleChanged(const QByteArray &current, const QByteArray &previous);
 266     void sortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous);
 267     void groupRoleChanged(const QByteArray &current, const QByteArray &previous);
 268     void groupOrderChanged(Qt::SortOrder current, Qt::SortOrder previous);
 269
 270 protected:
 271     /**
 272      * Is invoked if the grouped sorting has been changed by KItemModelBase::setGroupedSorting(). Allows
 273      * to react on the changed grouped sorting  before the signal groupedSortingChanged() will be emitted.
 274      */
 275     virtual void onGroupedSortingChanged(bool current);
 276
 277     /**
 278      * Is invoked if the sort role has been changed by KItemModelBase::setSortRole(). Allows
 279      * to react on the changed sort role before the signal sortRoleChanged() will be emitted.
 280      * The implementation must assure that the items are sorted by the role given by \a current.
 281      * Usually the most efficient way is to emit a
 282      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 283      * itemsInserted() signal afterwards.
 284      * The implementation should resort only if \a resortItems is true.
 285      */
 286     virtual void onSortRoleChanged(const QByteArray &current, const QByteArray &previous, bool resortItems = true);
 287
 288     /**
 289      * Is invoked if the sort order has been changed by KItemModelBase::setSortOrder(). Allows
 290      * to react on the changed sort order before the signal sortOrderChanged() will be emitted.
 291      * The implementation must assure that the items are sorted by the order given by \a current.
 292      * Usually the most efficient way is to emit a
 293      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 294      * itemsInserted() signal afterwards.
 295      */
 296     virtual void onSortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous, bool resortItems = true);
 297
 298     /**
 299      * Is invoked if the sort role has been changed by KItemModelBase::setSortRole(). Allows
 300      * to react on the changed sort role before the signal sortRoleChanged() will be emitted.
 301      * The implementation must assure that the items are sorted by the role given by \a current.
 302      * Usually the most efficient way is to emit a
 303      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 304      * itemsInserted() signal afterwards.
 305      * The implementation should resort only if \a regroupItems is true.
 306      */
 307     virtual void onGroupRoleChanged(const QByteArray &current, const QByteArray &previous, bool resortItems = true);
 308
 309     /**
 310      * Is invoked if the sort order has been changed by KItemModelBase::setSortOrder(). Allows
 311      * to react on the changed sort order before the signal sortOrderChanged() will be emitted.
 312      * The implementation must assure that the items are sorted by the order given by \a current.
 313      * Usually the most efficient way is to emit a
 314      * itemsRemoved() signal for all items, reorder the items internally and to emit a
 315      * itemsInserted() signal afterwards.
 316      */
 317     virtual void onGroupOrderChanged(Qt::SortOrder current, Qt::SortOrder previous, bool resortItems = true);
 318
 319 private:
 320     bool m_groupedSorting;
 321     QByteArray m_sortRole;
 322     Qt::SortOrder m_sortOrder;
 323     QByteArray m_groupRole;
 324     Qt::SortOrder m_groupOrder;
 325 };
 326
 327 inline Qt::SortOrder KItemModelBase::sortOrder() const
 328 {
 329     return m_sortOrder;
 330 }
 331
 332 inline Qt::SortOrder KItemModelBase::groupOrder() const
 333 {
 334     return m_groupOrder;
 335 }
 336
 337 #endif