src/kitemviews/private/kitemlistviewlayouter.h

   1 /***************************************************************************
   2  *   Copyright (C) 2011 by Peter Penz <peter.penz19@gmail.com>             *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  *                                                                         *
   9  *   This program is distributed in the hope that it will be useful,       *
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU General Public License     *
  15  *   along with this program; if not, write to the                         *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA            *
  18  ***************************************************************************/
  19
  20 #ifndef KITEMLISTVIEWLAYOUTER_H
  21 #define KITEMLISTVIEWLAYOUTER_H
  22
  23 #include <libdolphin_export.h>
  24
  25 #include <QObject>
  26 #include <QRectF>
  27 #include <QSet>
  28 #include <QSizeF>
  29
  30 class KItemModelBase;
  31 class KItemListSizeHintResolver;
  32
  33 /**
  34  * @brief Internal helper class for KItemListView to layout the items.
  35  *
  36  * The layouter is capable to align the items within a grid. If the
  37  * scroll-direction is horizontal the column-width of the grid can be
  38  * variable. If the scroll-direction is vertical the row-height of
  39  * the grid can be variable.
  40  *
  41  * The layouter is implemented in a way that it postpones the expensive
  42  * layout operation until a property is read the first time after
  43  * marking the layouter as dirty (see markAsDirty()). This means that
  44  * changing properties of the layouter is not expensive, only the
  45  * first read of a property can get expensive.
  46  */
  47 class LIBDOLPHINPRIVATE_EXPORT KItemListViewLayouter : public QObject
  48 {
  49     Q_OBJECT
  50
  51 public:
  52     KItemListViewLayouter(QObject* parent = 0);
  53     virtual ~KItemListViewLayouter();
  54
  55     void setScrollOrientation(Qt::Orientation orientation);
  56     Qt::Orientation scrollOrientation() const;
  57
  58     void setSize(const QSizeF& size);
  59     QSizeF size() const;
  60
  61     void setItemSize(const QSizeF& size);
  62     QSizeF itemSize() const;
  63
  64     /**
  65      * Margin between the rows and columns of items.
  66      */
  67     void setItemMargin(const QSizeF& margin);
  68     QSizeF itemMargin() const;
  69
  70     /**
  71      * Sets the height of the header that is always aligned
  72      * at the top. A height of <= 0.0 means that no header is
  73      * used.
  74      */
  75     void setHeaderHeight(qreal height);
  76     qreal headerHeight() const;
  77
  78     /**
  79      * Sets the height of the group header that is used
  80      * to indicate a new item group.
  81      */
  82     void setGroupHeaderHeight(qreal height);
  83     qreal groupHeaderHeight() const;
  84
  85     /**
  86      * Sets the margin between the last items of the group n and
  87      * the group header for the group n + 1.
  88      */
  89     void setGroupHeaderMargin(qreal margin);
  90     qreal groupHeaderMargin() const;
  91
  92     void setScrollOffset(qreal scrollOffset);
  93     qreal scrollOffset() const;
  94
  95     qreal maximumScrollOffset() const;
  96
  97     void setItemOffset(qreal scrollOffset);
  98     qreal itemOffset() const;
  99
 100     qreal maximumItemOffset() const;
 101
 102     void setModel(const KItemModelBase* model);
 103     const KItemModelBase* model() const;
 104
 105     void setSizeHintResolver(const KItemListSizeHintResolver* sizeHintResolver);
 106     const KItemListSizeHintResolver* sizeHintResolver() const;
 107
 108     /**
 109      * @return The first (at least partly) visible index. -1 is returned
 110      *         if the item count is 0.
 111      */
 112     int firstVisibleIndex() const;
 113
 114     /**
 115      * @return The last (at least partly) visible index. -1 is returned
 116      *         if the item count is 0.
 117      */
 118     int lastVisibleIndex() const;
 119
 120     /**
 121      * @return Rectangle of the item with the index \a index.
 122      *         The top/left of the bounding rectangle is related to
 123      *         the top/left of the KItemListView. An empty rectangle
 124      *         is returned if an invalid index is given.
 125      */
 126     QRectF itemRect(int index) const;
 127
 128     /**
 129      * @return Rectangle of the group header for the item with the
 130      *         index \a index. Note that the layouter does not check
 131      *         whether the item really has a header: Usually only
 132      *         the first item of a group gets a header (see
 133      *         isFirstGroupItem()).
 134      */
 135     QRectF groupHeaderRect(int index) const;
 136
 137     /**
 138      * @return Column of the item with the index \a index.
 139      *         -1 is returned if an invalid index is given.
 140      */
 141     int itemColumn(int index) const;
 142
 143     /**
 144      * @return Row of the item with the index \a index.
 145      *         -1 is returned if an invalid index is given.
 146      */
 147     int itemRow(int index) const;
 148
 149     /**
 150      * @return Maximum number of (at least partly) visible items for
 151      *         the given size.
 152      */
 153     int maximumVisibleItems() const;
 154
 155     /**
 156      * @return True if the item with the index \p itemIndex
 157      *         is the first item within a group.
 158      */
 159     bool isFirstGroupItem(int itemIndex) const;
 160
 161     /**
 162      * Marks the layouter as dirty. This means as soon as a property of
 163      * the layouter gets read, an expensive relayout will be done.
 164      */
 165     void markAsDirty();
 166
 167     inline int columnCount() const
 168     {
 169         return m_columnCount;
 170     }
 171
 172 #ifndef QT_NO_DEBUG
 173     /**
 174      * @return True if the layouter has been marked as dirty and hence has
 175      *         not called yet doLayout(). Is enabled only in the debugging
 176      *         mode, as it is not useful to check the dirty state otherwise.
 177      */
 178     bool isDirty();
 179 #endif
 180
 181 private:
 182     void doLayout();
 183     void updateVisibleIndexes();
 184     bool createGroupHeaders();
 185
 186     /**
 187      * @return Minimum width of group headers when grouping is enabled in the horizontal
 188      *         alignment mode. The header alignment is done like this:
 189      *         Header-1 Header-2 Header-3
 190      *         Item 1   Item 4   Item 7
 191      *         Item 2   Item 5   Item 8
 192      *         Item 3   Item 6   Item 9
 193      */
 194     qreal minimumGroupHeaderWidth() const;
 195
 196 private:
 197     bool m_dirty;
 198     bool m_visibleIndexesDirty;
 199
 200     Qt::Orientation m_scrollOrientation;
 201     QSizeF m_size;
 202
 203     QSizeF m_itemSize;
 204     QSizeF m_itemMargin;
 205     qreal m_headerHeight;
 206     const KItemModelBase* m_model;
 207     const KItemListSizeHintResolver* m_sizeHintResolver;
 208
 209     qreal m_scrollOffset;
 210     qreal m_maximumScrollOffset;
 211
 212     qreal m_itemOffset;
 213     qreal m_maximumItemOffset;
 214
 215     int m_firstVisibleIndex;
 216     int m_lastVisibleIndex;
 217
 218     qreal m_columnWidth;
 219     qreal m_xPosInc;
 220     int m_columnCount;
 221
 222     // Stores all item indexes that are the first item of a group.
 223     // Assures fast access for KItemListViewLayouter::isFirstGroupItem().
 224     QSet<int> m_groupItemIndexes;
 225     qreal m_groupHeaderHeight;
 226     qreal m_groupHeaderMargin;
 227
 228     struct ItemInfo {
 229         QRectF rect;
 230         int column;
 231         int row;
 232     };
 233     QList<ItemInfo> m_itemInfos;
 234
 235     friend class KItemListControllerTest;
 236 };
 237
 238 #endif
 239
 240