Item view for listing items in a categorized fashion optionally. More...

#include <kcategorizedview.h>

Inheritance diagram for KCategorizedView:

Public Member Functions
	KCategorizedView (QWidget *parent=0)
	~KCategorizedView ()
bool	alternatingBlockColors () const
QModelIndexList	block (const QModelIndex &representative)
QModelIndexList	block (const QString &category)
KCategoryDrawer *	categoryDrawer () const
int	categorySpacing () const
bool	collapsibleBlocks () const
virtual QModelIndex	indexAt (const QPoint &point) const
virtual void	reset ()
void	setAlternatingBlockColors (bool enable)
void	setCategoryDrawer (KCategoryDrawer *categoryDrawer)
void	setCategorySpacing (int categorySpacing)
void	setCollapsibleBlocks (bool enable)
void	setGridSize (const QSize &size)
void	setGridSizeOwn (const QSize &size)
virtual void	setModel (QAbstractItemModel *model)
virtual QRect	visualRect (const QModelIndex &index) const
Protected Slots
virtual void	rowsInsertedArtifficial (const QModelIndex &parent, int start, int end)
virtual void	rowsRemoved (const QModelIndex &parent, int start, int end)
virtual void	slotLayoutChanged ()
Protected Member Functions
virtual void	currentChanged (const QModelIndex &current, const QModelIndex &previous)
virtual void	dataChanged (const QModelIndex &topLeft, const QModelIndex &bottomRight)
virtual void	dragEnterEvent (QDragEnterEvent *event)
virtual void	dragLeaveEvent (QDragLeaveEvent *event)
virtual void	dragMoveEvent (QDragMoveEvent *event)
virtual void	dropEvent (QDropEvent *event)
virtual void	leaveEvent (QEvent *event)
virtual void	mouseMoveEvent (QMouseEvent *event)
virtual void	mousePressEvent (QMouseEvent *event)
virtual void	mouseReleaseEvent (QMouseEvent *event)
virtual QModelIndex	moveCursor (CursorAction cursorAction, Qt::KeyboardModifiers modifiers)
virtual void	paintEvent (QPaintEvent *event)
virtual void	resizeEvent (QResizeEvent *event)
virtual void	rowsAboutToBeRemoved (const QModelIndex &parent, int start, int end)
virtual void	rowsInserted (const QModelIndex &parent, int start, int end)
virtual void	setSelection (const QRect &rect, QItemSelectionModel::SelectionFlags flags)
virtual void	startDrag (Qt::DropActions supportedActions)
virtual void	updateGeometries ()
Properties
bool	alternatingBlockColors
int	categorySpacing
bool	collapsibleBlocks

Detailed Description

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 also:
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 also:
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").; 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 also:: KCategorizedSortFilterProxyModel, KCategoryDrawer

Author:: Rafael Fernández López <ereslibre@kde.org>

Definition at line 79 of file kcategorizedview.h.

Constructor & Destructor Documentation

KCategorizedView::KCategorizedView ( QWidget * parent = 0 )

Definition at line 498 of file kcategorizedview.cpp.

KCategorizedView::~KCategorizedView ( )

Definition at line 504 of file kcategorizedview.cpp.

Member Function Documentation

bool KCategorizedView::alternatingBlockColors ( ) const

Returns:: Whether blocks should be drawn with alternating colors.

Since:: 4.4

QModelIndexList KCategorizedView::block ( const QString & category )

Returns:: Block of indexes that are into category.

Since:: 4.5

Definition at line 688 of file kcategorizedview.cpp.

QModelIndexList KCategorizedView::block ( const QModelIndex & representative )

Returns:: Block of indexes that are represented by representative.

Since:: 4.5

Definition at line 706 of file kcategorizedview.cpp.

KCategoryDrawer * KCategorizedView::categoryDrawer ( ) const

Returns the current category drawer.

Definition at line 627 of file kcategorizedview.cpp.

int KCategorizedView::categorySpacing ( ) const

Returns:: Category spacing. The spacing between categories.

Since:: 4.4

bool KCategorizedView::collapsibleBlocks ( ) const

Returns:: Whether blocks can be collapsed or not.

Since:: 4.4

void KCategorizedView::currentChanged	(	const QModelIndex &	current,
		const QModelIndex &	previous
	)		`[protected, virtual]`

Reimplemented from QAbstractItemView.

Definition at line 1380 of file kcategorizedview.cpp.

void KCategorizedView::dataChanged	(	const QModelIndex &	topLeft,
		const QModelIndex &	bottomRight
	)		`[protected, virtual]`

Reimplemented from QAbstractItemView.

Definition at line 1386 of file kcategorizedview.cpp.

void KCategorizedView::dragEnterEvent ( QDragEnterEvent * event ) [protected, virtual]

Reimplemented from QAbstractItemView.

Definition at line 1071 of file kcategorizedview.cpp.

void KCategorizedView::dragLeaveEvent ( QDragLeaveEvent * event ) [protected, virtual]

Reimplemented from QAbstractItemView.

Definition at line 1076 of file kcategorizedview.cpp.

void KCategorizedView::dragMoveEvent ( QDragMoveEvent * event ) [protected, virtual]

Reimplemented from QAbstractItemView.

Definition at line 1065 of file kcategorizedview.cpp.

void KCategorizedView::dropEvent ( QDropEvent * event ) [protected, virtual]

Reimplemented from QAbstractItemView.

Definition at line 1081 of file kcategorizedview.cpp.

QModelIndex KCategorizedView::indexAt ( const QPoint & point ) const [virtual]

Reimplemented from QAbstractItemView.

Definition at line 711 of file kcategorizedview.cpp.

void KCategorizedView::leaveEvent ( QEvent * event ) [protected, virtual]

Reimplemented from QWidget.

Definition at line 1043 of file kcategorizedview.cpp.

void KCategorizedView::mouseMoveEvent ( QMouseEvent * event ) [protected, virtual]

Reimplemented from QWidget.

Definition at line 919 of file kcategorizedview.cpp.

void KCategorizedView::mousePressEvent ( QMouseEvent * event ) [protected, virtual]

Reimplemented from QWidget.

Definition at line 978 of file kcategorizedview.cpp.

void KCategorizedView::mouseReleaseEvent ( QMouseEvent * event ) [protected, virtual]

Reimplemented from QWidget.

Definition at line 1012 of file kcategorizedview.cpp.

QModelIndex KCategorizedView::moveCursor	(	CursorAction	cursorAction,
		Qt::KeyboardModifiers	modifiers
	)		`[protected, virtual]`

Reimplemented from QAbstractItemView.

Definition at line 1088 of file kcategorizedview.cpp.

void KCategorizedView::paintEvent ( QPaintEvent * event ) [protected, virtual]

Reimplemented from QWidget.

Definition at line 759 of file kcategorizedview.cpp.

void KCategorizedView::reset ( ) [virtual]

Reimplemented from QAbstractItemView.

Definition at line 753 of file kcategorizedview.cpp.

void KCategorizedView::resizeEvent ( QResizeEvent * event ) [protected, virtual]

Reimplemented from QWidget.

Definition at line 869 of file kcategorizedview.cpp.

void KCategorizedView::rowsAboutToBeRemoved	(	const QModelIndex &	parent,
		int	start,
		int	end
	)		`[protected, virtual]`

Reimplemented from QAbstractItemView.

Definition at line 1205 of file kcategorizedview.cpp.

void KCategorizedView::rowsInserted	(	const QModelIndex &	parent,
		int	start,
		int	end
	)		`[protected, virtual]`

Reimplemented from QAbstractItemView.

Definition at line 1418 of file kcategorizedview.cpp.

void KCategorizedView::rowsInsertedArtifficial	(	const QModelIndex &	parent,
		int	start,
		int	end
	)		`[protected, virtual, slot]`

Warning:: Deprecated since 4.4.

Definition at line 1433 of file kcategorizedview.cpp.

void KCategorizedView::rowsRemoved	(	const QModelIndex &	parent,
		int	start,
		int	end
	)		`[protected, virtual, slot]`

Warning:: Deprecated since 4.4.

Definition at line 1444 of file kcategorizedview.cpp.

void KCategorizedView::setAlternatingBlockColors ( bool enable )

Sets whether blocks should be drawn with alternating colors.

Since:: 4.4

Definition at line 673 of file kcategorizedview.cpp.

void KCategorizedView::setCategoryDrawer ( KCategoryDrawer * categoryDrawer )

The category drawer that will be used for drawing categories.

Definition at line 632 of file kcategorizedview.cpp.

void KCategorizedView::setCategorySpacing ( int categorySpacing )

Stablishes the category spacing.

This is the spacing between categories.

Since:: 4.4

Definition at line 654 of file kcategorizedview.cpp.

void KCategorizedView::setCollapsibleBlocks ( bool enable )

Sets whether blocks can be collapsed or not.

Since:: 4.4

Definition at line 683 of file kcategorizedview.cpp.

void KCategorizedView::setGridSize ( const QSize & size )

Calls to setGridSizeOwn().

Definition at line 535 of file kcategorizedview.cpp.

void KCategorizedView::setGridSizeOwn ( 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:

     QListView *lv = new KCategorizedView();
     lv->setGridSize(mySize);

will not call to the expected setGridSize method. Instead do something like this:

     QListView *lv;
     ...
     KCategorizedView *cv = qobject_cast<KCategorizedView*>(lv);
     if (cv) {
         cv->setGridSizeOwn(mySize);
     } else {
         lv->setGridSize(mySize);
     }

Note:: this method will call to QListView::setGridSize among other operations.

Since:: 4.4

Definition at line 540 of file kcategorizedview.cpp.

void KCategorizedView::setModel ( QAbstractItemModel * model ) [virtual]

Reimplemented from QAbstractItemView.

Definition at line 509 of file kcategorizedview.cpp.

void KCategorizedView::setSelection	(	const QRect &	rect,
		QItemSelectionModel::SelectionFlags	flags
	)		`[protected, virtual]`

Reimplemented from QAbstractItemView.

Definition at line 875 of file kcategorizedview.cpp.

void KCategorizedView::slotLayoutChanged ( ) [protected, virtual, slot]

Reposition items as needed.

Definition at line 1454 of file kcategorizedview.cpp.

void KCategorizedView::startDrag ( Qt::DropActions supportedActions ) [protected, virtual]

Reimplemented from QAbstractItemView.

Definition at line 1060 of file kcategorizedview.cpp.

void KCategorizedView::updateGeometries ( ) [protected, virtual]

Reimplemented from QAbstractItemView.

Definition at line 1327 of file kcategorizedview.cpp.

QRect KCategorizedView::visualRect ( const QModelIndex & index ) const [virtual]

Reimplemented from QAbstractItemView.

Definition at line 546 of file kcategorizedview.cpp.

Property Documentation

bool KCategorizedView::alternatingBlockColors [read, write]

Definition at line 84 of file kcategorizedview.h.

int KCategorizedView::categorySpacing [read, write]

Definition at line 83 of file kcategorizedview.h.

bool KCategorizedView::collapsibleBlocks [read, write]

Definition at line 85 of file kcategorizedview.h.

The documentation for this class was generated from the following files:

KDEUI

KCategorizedView Class Reference

Public Member Functions

Protected Slots

Protected Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation

KDEUI

kdelibs