X-Git-Url: https://cloud.milkyroute.net/gitweb/dolphin.git/blobdiff_plain/7424fcc3314a63d0716cb428a8b8de24b23e0279..16e3d669de256aab86f957cd5b3bee91bd2fbbff:/src/kitemviews/kitemmodelbase.h diff --git a/src/kitemviews/kitemmodelbase.h b/src/kitemviews/kitemmodelbase.h index 763a02efd..bd5ca1d65 100644 --- a/src/kitemviews/kitemmodelbase.h +++ b/src/kitemviews/kitemmodelbase.h @@ -23,44 +23,39 @@ #ifndef KITEMMODELBASE_H #define KITEMMODELBASE_H -#include +#include "dolphin_export.h" + +#include +#include #include #include -#include #include class QMimeData; -struct KItemRange -{ - KItemRange(int index = 0, int count = 0); - int index; - int count; - - bool operator == (const KItemRange& other) const; -}; -typedef QList KItemRangeList; - /** * @brief Base class for model implementations used by KItemListView and KItemListController. * - * A item-model consists of a variable number of items. The number of items + * An item-model consists of a variable number of items. The number of items * is given by KItemModelBase::count(). The data of an item is accessed by a unique index * with KItemModelBase::data(). The indexes are integer-values counting from 0 to the * KItemModelBase::count() - 1. * * One item consists of a variable number of role/value-pairs. * - * A model can optionally provide sorting- and/or grouping-capabilities. + * A model can optionally provide sorting- and grouping-capabilities. + * + * Also optionally it is possible to provide a tree of items by implementing the methods + * setExpanded(), isExpanded(), isExpandable() and expandedParentsCount(). */ -class LIBDOLPHINPRIVATE_EXPORT KItemModelBase : public QObject +class DOLPHIN_EXPORT KItemModelBase : public QObject { Q_OBJECT public: KItemModelBase(QObject* parent = 0); - KItemModelBase(const QByteArray& groupRole, const QByteArray& sortRole, QObject* parent = 0); + explicit KItemModelBase(const QByteArray& sortRole, QObject* parent = 0); virtual ~KItemModelBase(); /** @return The number of items. */ @@ -78,26 +73,13 @@ public: virtual bool setData(int index, const QHash& values); /** - * @return True if the model supports grouping of data. Per default false is returned. - * If the model should support grouping it is necessary to overwrite - * this method to return true and to implement KItemModelBase::onGroupRoleChanged(). - */ - virtual bool supportsGrouping() const; - - /** - * Sets the group-role to \a role. The method KItemModelBase::onGroupRoleChanged() will be - * called so that model-implementations can react on the group-role change. Afterwards the - * signal groupRoleChanged() will be emitted. + * Enables/disables the grouped sorting. The method KItemModelBase::onGroupedSortingChanged() will be + * called so that model-implementations can react on the grouped-sorting change. Afterwards the + * signal groupedSortingChanged() will be emitted. If the grouped sorting is enabled, the method + * KItemModelBase::groups() must be implemented. */ - void setGroupRole(const QByteArray& role); - QByteArray groupRole() const; - - /** - * @return True if the model supports sorting of data. Per default false is returned. - * If the model should support sorting it is necessary to overwrite - * this method to return true and to implement KItemModelBase::onSortRoleChanged(). - */ - virtual bool supportsSorting() const; + void setGroupedSorting(bool grouped); + bool groupedSorting() const; /** * Sets the sort-role to \a role. The method KItemModelBase::onSortRoleChanged() will be @@ -121,12 +103,53 @@ public: */ virtual QString roleDescription(const QByteArray& role) const; + /** + * @return List of group headers. Each list-item consists of the index of the item + * that represents the first item of a group and a value represented + * as QVariant. The value is shown by an instance of KItemListGroupHeader. + * Per default an empty list is returned. + */ + virtual QList > groups() const; + + /** + * Expands the item with the index \a index if \a expanded is true. + * If \a expanded is false the item will be collapsed. + * + * Per default no expanding of items is implemented. When implementing + * this method it is mandatory to overwrite KItemModelBase::isExpandable() + * and KItemListView::supportsExpandableItems() to return true. + * + * @return True if the operation has been successful. + */ + virtual bool setExpanded(int index, bool expanded); + + /** + * @return True if the item with the index \a index is expanded. + * Per default no expanding of items is implemented. When implementing + * this method it is mandatory to overwrite KItemModelBase::isExpandable() + * and KItemListView::supportsExpandableItems() to return true. + */ + virtual bool isExpanded(int index) const; + + /** + * @return True if expanding and collapsing of the item with the index \a index + * is supported. Per default false is returned. + */ + virtual bool isExpandable(int index) const; + + /** + * @return Number of expanded parent items for the item with the given index. + * Per default 0 is returned. + */ + virtual int expandedParentsCount(int index) const; + /** * @return MIME-data for the items given by \a indexes. The default implementation * returns 0. The ownership of the returned instance is in the hand of the - * caller of this method. + * caller of this method. The method must be implemented if dragging of + * items should be possible. */ - virtual QMimeData* createMimeData(const QSet& indexes) const; + virtual QMimeData* createMimeData(const KItemSet& indexes) const; /** * @return Reimplement this to return the index for the first item @@ -187,25 +210,30 @@ signals: * with the items 5 and 6 then the parameters look like this: * - itemRange: has the index 0 and a count of 7. * - movedToIndexes: Contains the seven values 5, 6, 2, 3, 4, 0, 1 + * + * This signal implies that the groups might have changed. Therefore, + * gropusChanged() is not emitted if this signal is emitted. */ void itemsMoved(const KItemRange& itemRange, const QList& movedToIndexes); void itemsChanged(const KItemRangeList& itemRanges, const QSet& roles); - void groupRoleChanged(const QByteArray& current, const QByteArray& previous); + /** + * Is emitted if the groups have changed, even though the order of the + * items has not been modified. + */ + void groupsChanged(); + + void groupedSortingChanged(bool current); void sortRoleChanged(const QByteArray& current, const QByteArray& previous); void sortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous); protected: /** - * Is invoked if the group role has been changed by KItemModelBase::setGroupRole(). Allows - * to react on the changed group role before the signal groupRoleChanged() will be emitted. - * The implementation must assure that the items are sorted in a way that they are grouped - * by the role given by \a current. Usually the most efficient way is to emit a - * itemsRemoved() signal for all items, reorder the items internally and to emit a - * itemsInserted() signal afterwards. + * Is invoked if the grouped sorting has been changed by KItemModelBase::setGroupedSorting(). Allows + * to react on the changed grouped sorting before the signal groupedSortingChanged() will be emitted. */ - virtual void onGroupRoleChanged(const QByteArray& current, const QByteArray& previous); + virtual void onGroupedSortingChanged(bool current); /** * Is invoked if the sort role has been changed by KItemModelBase::setSortRole(). Allows @@ -228,7 +256,7 @@ protected: virtual void onSortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous); private: - QByteArray m_groupRole; + bool m_groupedSorting; QByteArray m_sortRole; Qt::SortOrder m_sortOrder; };