pollymc/libgroupview/include/kcategorizedview.h

334 lines
9.8 KiB
C++

/**
* This file is part of the KDE project
* Copyright (C) 2007, 2009 Rafael Fernández López <ereslibre@kde.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
#ifndef KCATEGORIZEDVIEW_H
#define KCATEGORIZEDVIEW_H
#include <QListView>
//#include <kdeui_export.h>
#include <libgroupview_config.h>
class KCategoryDrawer;
/**
* @short Item view for listing items in a categorized fashion optionally
*
* KCategorizedView basically has the same functionality as QListView, only that it also lets you
* layout items in a way that they are categorized visually.
*
* For it to work you will need to set a KCategorizedSortFilterProxyModel and a KCategoryDrawer
* with methods setModel() and setCategoryDrawer() respectively. Also, the model will need to be
* flagged as categorized with KCategorizedSortFilterProxyModel::setCategorizedModel(true).
*
* The way it works (if categorization enabled):
*
* - When sorting, it does more things than QListView does. It will ask the model for the
* special role CategorySortRole (@see KCategorizedSortFilterProxyModel). This can return
* a QString or an int in order to tell the view the order of categories. In this sense, for
* instance, if we are sorting by name ascending, "A" would be before than "B". If we are
* sorting by size ascending, 512 bytes would be before 1024 bytes. This way categories are
* also sorted.
*
* - When the view has to paint, it will ask the model with the role CategoryDisplayRole
* (@see KCategorizedSortFilterProxyModel). It will for instance return "F" for "foo.pdf" if
* we are sorting by name ascending, or "Small" if a certain item has 100 bytes, for example.
*
* For drawing categories, KCategoryDrawer will be used. You can inherit this class to do your own
* drawing.
*
* @note All examples cited before talk about filesystems and such, but have present that this
* is a completely generic class, and it can be used for whatever your purpose is. For
* instance when talking about animals, you can separate them by "Mammal" and "Oviparous". In
* this very case, for example, the CategorySortRole and the CategoryDisplayRole could be the
* same ("Mammal" and "Oviparous").
*
* @note There is a really performance boost if CategorySortRole returns an int instead of a QString.
* Have present that this role is asked (n * log n) times when sorting and compared. Comparing
* ints is always faster than comparing strings, whithout mattering how fast the string
* comparison is. Consider thinking of a way of returning ints instead of QStrings if your
* model can contain a high number of items.
*
* @warning Note that for really drawing items in blocks you will need some things to be done:
* - The model set to this view has to be (or inherit if you want to do special stuff
* in it) KCategorizedSortFilterProxyModel.
* - This model needs to be set setCategorizedModel to true.
* - Set a category drawer by calling setCategoryDrawer.
*
* @see KCategorizedSortFilterProxyModel, KCategoryDrawer
*
* @author Rafael Fernández López <ereslibre@kde.org>
*/
class LIBGROUPVIEW_EXPORT KCategorizedView
: public QListView
{
Q_OBJECT
Q_PROPERTY ( int categorySpacing READ categorySpacing WRITE setCategorySpacing )
Q_PROPERTY ( bool alternatingBlockColors READ alternatingBlockColors WRITE setAlternatingBlockColors )
Q_PROPERTY ( bool collapsibleBlocks READ collapsibleBlocks WRITE setCollapsibleBlocks )
public:
KCategorizedView ( QWidget *parent = 0 );
~KCategorizedView();
/**
* Reimplemented from QAbstractItemView.
*/
virtual void setModel ( QAbstractItemModel *model );
/**
* Calls to setGridSizeOwn().
*/
void setGridSize ( const QSize &size );
/**
* @warning note that setGridSize is not virtual in the base class (QListView), so if you are
* calling to this method, make sure you have a KCategorizedView pointer around. This
* means that something like:
* @code
* QListView *lv = new KCategorizedView();
* lv->setGridSize(mySize);
* @endcode
*
* will not call to the expected setGridSize method. Instead do something like this:
*
* @code
* QListView *lv;
* ...
* KCategorizedView *cv = qobject_cast<KCategorizedView*>(lv);
* if (cv) {
* cv->setGridSizeOwn(mySize);
* } else {
* lv->setGridSize(mySize);
* }
* @endcode
*
* @note this method will call to QListView::setGridSize among other operations.
*
* @since 4.4
*/
void setGridSizeOwn ( const QSize &size );
/**
* Reimplemented from QAbstractItemView.
*/
virtual QRect visualRect ( const QModelIndex &index ) const;
/**
* Returns the current category drawer.
*/
KCategoryDrawer *categoryDrawer() const;
/**
* The category drawer that will be used for drawing categories.
*/
void setCategoryDrawer ( KCategoryDrawer *categoryDrawer );
/**
* @return Category spacing. The spacing between categories.
*
* @since 4.4
*/
int categorySpacing() const;
/**
* Stablishes the category spacing. This is the spacing between categories.
*
* @since 4.4
*/
void setCategorySpacing ( int categorySpacing );
/**
* @return Whether blocks should be drawn with alternating colors.
*
* @since 4.4
*/
bool alternatingBlockColors() const;
/**
* Sets whether blocks should be drawn with alternating colors.
*
* @since 4.4
*/
void setAlternatingBlockColors ( bool enable );
/**
* @return Whether blocks can be collapsed or not.
*
* @since 4.4
*/
bool collapsibleBlocks() const;
/**
* Sets whether blocks can be collapsed or not.
*
* @since 4.4
*/
void setCollapsibleBlocks ( bool enable );
/**
* @return Block of indexes that are into @p category.
*
* @since 4.5
*/
QModelIndexList block ( const QString &category );
/**
* @return Block of indexes that are represented by @p representative.
*
* @since 4.5
*/
QModelIndexList block ( const QModelIndex &representative );
/**
* Reimplemented from QAbstractItemView.
*/
virtual QModelIndex indexAt ( const QPoint &point ) const;
/**
* Reimplemented from QAbstractItemView.
*/
virtual void reset();
/**
* Signify that all item delegates size hints return the same fixed size
*/
void setUniformItemWidths(bool enable);
/**
* Do all item delegate size hints return the same fixed size?
*/
bool uniformItemWidths() const;
protected:
/**
* Reimplemented from QWidget.
*/
virtual void paintEvent ( QPaintEvent *event );
/**
* Reimplemented from QWidget.
*/
virtual void resizeEvent ( QResizeEvent *event );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void setSelection ( const QRect &rect,
QItemSelectionModel::SelectionFlags flags );
/**
* Reimplemented from QWidget.
*/
virtual void mouseMoveEvent ( QMouseEvent *event );
/**
* Reimplemented from QWidget.
*/
virtual void mousePressEvent ( QMouseEvent *event );
/**
* Reimplemented from QWidget.
*/
virtual void mouseReleaseEvent ( QMouseEvent *event );
/**
* Reimplemented from QWidget.
*/
virtual void leaveEvent ( QEvent *event );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void startDrag ( Qt::DropActions supportedActions );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void dragMoveEvent ( QDragMoveEvent *event );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void dragEnterEvent ( QDragEnterEvent *event );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void dragLeaveEvent ( QDragLeaveEvent *event );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void dropEvent ( QDropEvent *event );
/**
* Reimplemented from QAbstractItemView.
*/
virtual QModelIndex moveCursor ( CursorAction cursorAction,
Qt::KeyboardModifiers modifiers );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void rowsAboutToBeRemoved ( const QModelIndex &parent,
int start,
int end );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void updateGeometries();
/**
* Reimplemented from QAbstractItemView.
*/
virtual void currentChanged ( const QModelIndex &current,
const QModelIndex &previous );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void dataChanged ( const QModelIndex &topLeft,
const QModelIndex &bottomRight );
/**
* Reimplemented from QAbstractItemView.
*/
virtual void rowsInserted ( const QModelIndex &parent,
int start,
int end );
protected Q_SLOTS:
/**
* @internal
* Reposition items as needed.
*/
virtual void slotLayoutChanged();
virtual void slotCollapseOrExpandClicked ( QModelIndex );
private:
class Private;
Private *const d;
};
#endif // KCATEGORIZEDVIEW_H