src/kitemviews/kitemmodelbase.h

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