KCategorizedView

KDE 4.5 PyKDE API Reference

- KDE's Python API

# KCategorizedView Class Reference

`from PyKDE4.kdeui import *`

Inherits: QListView → QAbstractItemView → QAbstractScrollArea → QFrame → QWidget → QObject

## 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 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 also:
  KCategorizedSortFilterProxyModel, KCategoryDrawer

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

## Methods
| __init__ (self, QWidget parent=0)
bool | alternatingBlockColors (self)
[QModelIndex] | block (self, QString category)
[QModelIndex] | block (self, QModelIndex representative)
KCategoryDrawer | categoryDrawer (self)
int | categorySpacing (self)
bool | collapsibleBlocks (self)
| currentChanged (self, QModelIndex current, QModelIndex previous)
| dataChanged (self, QModelIndex topLeft, QModelIndex bottomRight)
| dragEnterEvent (self, QDragEnterEvent event)
| dragLeaveEvent (self, QDragLeaveEvent event)
| dragMoveEvent (self, QDragMoveEvent event)
| dropEvent (self, QDropEvent event)
QModelIndex | indexAt (self, QPoint point)
| leaveEvent (self, QEvent event)
| mouseMoveEvent (self, QMouseEvent event)
| mousePressEvent (self, QMouseEvent event)
| mouseReleaseEvent (self, QMouseEvent event)
QModelIndex | moveCursor (self, QAbstractItemView.CursorAction cursorAction, Qt::KeyboardModifiers modifiers)
| paintEvent (self, QPaintEvent event)
| reset (self)
| resizeEvent (self, QResizeEvent event)
| rowsAboutToBeRemoved (self, QModelIndex parent, int start, int end)
| rowsInserted (self, QModelIndex parent, int start, int end)
| rowsInsertedArtifficial (self, QModelIndex parent, int start, int end)
| rowsRemoved (self, QModelIndex parent, int start, int end)
| setAlternatingBlockColors (self, bool enable)
| setCategoryDrawer (self, KCategoryDrawer categoryDrawer)
| setCategorySpacing (self, int categorySpacing)
| setCollapsibleBlocks (self, bool enable)
| setGridSize (self, QSize size)
| setGridSizeOwn (self, QSize size)
| setModel (self, QAbstractItemModel model)
| setSelection (self, QRect rect, QItemSelectionModel.SelectionFlags flags)
| slotLayoutChanged (self)
| startDrag (self, Qt::DropActions supportedActions)
| updateGeometries (self)
QRect | visualRect (self, QModelIndex index)

## Method Documentation

__init__ | ( | self, |
|  | QWidget | parent=0
| ) |  |  |

bool alternatingBlockColors | ( |  | self ) |

Returns:
  Whether blocks should be drawn with alternating colors.

Since:
  4.4

[QModelIndex] block | ( | self, |
|  | QString | category
| ) |  |  |

Returns:
  Block of indexes that are represented by representative.

Since:
  4.5

[QModelIndex] block | ( | self, |
|  | QModelIndex | representative
| ) |  |  |

Returns:
  Block of indexes that are represented by representative.

Since:
  4.5

KCategoryDrawer categoryDrawer | ( |  | self ) |

Returns the current category drawer.

int categorySpacing | ( |  | self ) |

Returns:
  Category spacing. The spacing between categories.

Since:
  4.4

bool collapsibleBlocks | ( |  | self ) |

Returns:
  Whether blocks can be collapsed or not.

Since:
  4.4

currentChanged | ( | self, |
|  | QModelIndex | current,
|  | QModelIndex | previous
| ) |  |  |

Reimplemented from QAbstractItemView.

dataChanged | ( | self, |
|  | QModelIndex | topLeft,
|  | QModelIndex | bottomRight
| ) |  |  |

Reimplemented from QAbstractItemView.

dragEnterEvent | ( | self, |
|  | QDragEnterEvent | event
| ) |  |  |

Reimplemented from QAbstractItemView.

dragLeaveEvent | ( | self, |
|  | QDragLeaveEvent | event
| ) |  |  |

Reimplemented from QAbstractItemView.

dragMoveEvent | ( | self, |
|  | QDragMoveEvent | event
| ) |  |  |

Reimplemented from QAbstractItemView.

dropEvent | ( | self, |
|  | QDropEvent | event
| ) |  |  |

Reimplemented from QAbstractItemView.

QModelIndex indexAt | ( | self, |
|  | QPoint | point
| ) |  |  |

Reimplemented from QAbstractItemView.

leaveEvent | ( | self, |
|  | QEvent | event
| ) |  |  |

Reimplemented from QWidget.

mouseMoveEvent | ( | self, |
|  | QMouseEvent | event
| ) |  |  |

Reimplemented from QWidget.

mousePressEvent | ( | self, |
|  | QMouseEvent | event
| ) |  |  |

Reimplemented from QWidget.

mouseReleaseEvent | ( | self, |
|  | QMouseEvent | event
| ) |  |  |

Reimplemented from QWidget.

QModelIndex moveCursor | ( | self, |
|  | QAbstractItemView.CursorAction | cursorAction,
|  | Qt::KeyboardModifiers | modifiers
| ) |  |  |

Reimplemented from QAbstractItemView.

paintEvent | ( | self, |
|  | QPaintEvent | event
| ) |  |  |

Reimplemented from QWidget.

reset | ( |  | self ) |

Reimplemented from QAbstractItemView.

resizeEvent | ( | self, |
|  | QResizeEvent | event
| ) |  |  |

Reimplemented from QWidget.

rowsAboutToBeRemoved | ( | self, |
|  | QModelIndex | parent,
|  | int | start,
|  | int | end
| ) |  |  |

Reimplemented from QAbstractItemView.

rowsInserted | ( | self, |
|  | QModelIndex | parent,
|  | int | start,
|  | int | end
| ) |  |  |

Reimplemented from QAbstractItemView.

rowsInsertedArtifficial | ( | self, |
|  | QModelIndex | parent,
|  | int | start,
|  | int | end
| ) |  |  |

Internal:

Warning:
  Deprecated since 4.4.

rowsRemoved | ( | self, |
|  | QModelIndex | parent,
|  | int | start,
|  | int | end
| ) |  |  |

Internal:

Warning:
  Deprecated since 4.4.

setAlternatingBlockColors | ( | self, |
|  | bool | enable
| ) |  |  |

Sets whether blocks should be drawn with alternating colors.

Since:
  4.4

setCategoryDrawer | ( | self, |
|  | KCategoryDrawer | categoryDrawer
| ) |  |  |

The category drawer that will be used for drawing categories.

setCategorySpacing | ( | self, |
|  | int | categorySpacing
| ) |  |  |

Stablishes the category spacing. This is the spacing between categories.

Since:
  4.4

setCollapsibleBlocks | ( | self, |
|  | bool | enable
| ) |  |  |

Sets whether blocks can be collapsed or not.

Since:
  4.4

setGridSize | ( | self, |
|  | QSize | size
| ) |  |  |

Calls to setGridSizeOwn().

setGridSizeOwn | ( | self, |
|  | 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

setModel | ( | self, |
|  | QAbstractItemModel | model
| ) |  |  |

Reimplemented from QAbstractItemView.

setSelection | ( | self, |
|  | QRect | rect,
|  | QItemSelectionModel.SelectionFlags | flags
| ) |  |  |

Reimplemented from QAbstractItemView.

slotLayoutChanged | ( |  | self ) |

Internal:
  Reposition items as needed.

startDrag | ( | self, |
|  | Qt::DropActions | supportedActions
| ) |  |  |

Reimplemented from QAbstractItemView.

updateGeometries | ( |  | self ) |

Reimplemented from QAbstractItemView.

QRect visualRect | ( | self, |
|  | QModelIndex | index
| ) |  |  |

Reimplemented from QAbstractItemView.