KDE API Reference

Contents

KCategorizedView Class

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

Header: #include <KCategorizedView>
CMake: find_package(KF6 REQUIRED COMPONENTS ItemViews)
target_link_libraries(mytarget PRIVATE KF6::ItemViews)
Inherits: QListView

Properties

Public Functions

KCategorizedView(QWidget *parent = nullptr)
(since 4.4) bool alternatingBlockColors() const
(since 4.5) QModelIndexList block(const QModelIndex &representative)
(since 4.5) QModelIndexList block(const QString &category)
KCategoryDrawer *categoryDrawer() const
(since 4.4) int categorySpacing() const
(since 4.4) bool collapsibleBlocks() const
(since 4.4) void setAlternatingBlockColors(bool enable)
void setCategoryDrawer(KCategoryDrawer *categoryDrawer)
(since 4.4) void setCategorySpacing(int categorySpacing)
(since 4.4) void setCollapsibleBlocks(bool enable)
void setGridSize(const QSize &size)
(since 4.4) void setGridSizeOwn(const QSize &size)

Signals

void alternatingBlockColorsChanged(bool enable)
void categorySpacingChanged(int spacing)
void collapsibleBlocksChanged(bool enable)

Detailed Description

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, without 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:

See also KCategorizedSortFilterProxyModel and KCategoryDrawer.

Property Documentation

alternatingBlockColors : bool

Access functions:

bool alternatingBlockColors() const
void setAlternatingBlockColors(bool enable)

Notifier signal:

void alternatingBlockColorsChanged(bool enable)

categorySpacing : int

Access functions:

int categorySpacing() const
void setCategorySpacing(int categorySpacing)

Notifier signal:

void categorySpacingChanged(int spacing)

collapsibleBlocks : bool

Access functions:

bool collapsibleBlocks() const
void setCollapsibleBlocks(bool enable)

Notifier signal:

void collapsibleBlocksChanged(bool enable)

Member Function Documentation

KCategorizedView::KCategorizedView(QWidget *parent = nullptr)

[since 4.4] bool KCategorizedView::alternatingBlockColors() const

Returns whether blocks should be drawn with alternating colors.

Note: Getter function for property alternatingBlockColors.

This function was introduced in 4.4.

See also setAlternatingBlockColors().

[signal] void KCategorizedView::alternatingBlockColorsChanged(bool enable)

Note: Notifier signal for property alternatingBlockColors.

[since 4.5] QModelIndexList KCategorizedView::block(const QModelIndex &representative)

Returns the block of indexes that are represented by representative.

This function was introduced in 4.5.

[since 4.5] QModelIndexList KCategorizedView::block(const QString &category)

Returns the block of indexes that are in category.

This function was introduced in 4.5.

KCategoryDrawer *KCategorizedView::categoryDrawer() const

Returns the current category drawer.

See also setCategoryDrawer().

[since 4.4] int KCategorizedView::categorySpacing() const

Returns the spacing between categories.

Note: Getter function for property categorySpacing.

This function was introduced in 4.4.

See also setCategorySpacing().

[signal] void KCategorizedView::categorySpacingChanged(int spacing)

Note: Notifier signal for property categorySpacing.

[since 4.4] bool KCategorizedView::collapsibleBlocks() const

Returns whether blocks can be collapsed or not.

Note: Getter function for property collapsibleBlocks.

This function was introduced in 4.4.

See also setCollapsibleBlocks().

[signal] void KCategorizedView::collapsibleBlocksChanged(bool enable)

Note: Notifier signal for property collapsibleBlocks.

[since 4.4] void KCategorizedView::setAlternatingBlockColors(bool enable)

Sets whether blocks should be drawn with alternating colors.

Note: Setter function for property alternatingBlockColors.

This function was introduced in 4.4.

See also alternatingBlockColors().

void KCategorizedView::setCategoryDrawer(KCategoryDrawer *categoryDrawer)

The category drawer that will be used for drawing categories.

See also categoryDrawer().

[since 4.4] void KCategorizedView::setCategorySpacing(int categorySpacing)

Sets the spacing between categories.

Note: Setter function for property categorySpacing.

This function was introduced in 4.4.

See also categorySpacing().

[since 4.4] void KCategorizedView::setCollapsibleBlocks(bool enable)

Sets whether blocks can be collapsed or not.

Note: Setter function for property collapsibleBlocks.

This function was introduced in 4.4.

See also collapsibleBlocks().

void KCategorizedView::setGridSize(const QSize &size)

Calls to setGridSizeOwn().

[since 4.4] 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.

This function was introduced in 4.4.