digiKam Developer Documentation: Digikam::DCategorizedSortFilterProxyModel Class Reference

| digiKam Developer Documentation Professional Photo Management with the Power of Open Source

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | List of all members
Digikam::DCategorizedSortFilterProxyModel Class Reference

This class lets you categorize a view. More...

Inheritance diagram for Digikam::DCategorizedSortFilterProxyModel:

## Public Types
enum | AdditionalRoles { CategoryDisplayRole = 0x17CE990A , CategorySortRole = 0x27857E60 }

## Public Member Functions
| DCategorizedSortFilterProxyModel (QObject *const parent=nullptr)
bool | isCategorizedModel () const
void | setCategorizedModel (bool categorizedModel)
| Enables or disables the categorization feature.
void | setSortCategoriesByNaturalComparison (bool sortCategoriesByNaturalComparison)
| Set if the sorting using CategorySortRole will use a natural comparison in the case that strings were returned.
void | sort (int column, Qt::SortOrder order=Qt::AscendingOrder) override
| Overridden from QSortFilterProxyModel.
bool | sortCategoriesByNaturalComparison () const
int | sortColumn () const
Qt::SortOrder | sortOrder () const

## Protected Member Functions
virtual int | compareCategories (const QModelIndex &left, const QModelIndex &right) const
| This method compares the category of the `left` index with the category of the `right` index.
bool | lessThan (const QModelIndex &left, const QModelIndex &right) const override
| Overridden from QSortFilterProxyModel.
virtual bool | subSortLessThan (const QModelIndex &left, const QModelIndex &right) const
| This method has a similar purpose as lessThan() has on QSortFilterProxyModel.

## Detailed Description

It is meant to be used along with DCategorizedView class.

In general terms all you need to do is to reimplement subSortLessThan() and compareCategories() methods. In order to make categorization work, you need to also call setCategorizedModel() class to enable it, since the categorization is disabled by default.

## Member Enumeration Documentation

## ◆ AdditionalRoles

enum Digikam::DCategorizedSortFilterProxyModel::AdditionalRoles

Enumerator
CategoryDisplayRole | This role is used for asking the category to a given index. Note use printf "0x%08X\n" $(($RANDOM*$RANDOM)) to define additional roles.
CategorySortRole | This role is used for sorting categories. You can return a string or a long long value. Strings will be sorted alphabetically while long long will be sorted by their value. Please note that this value won't be shown on the view, is only for sorting purposes. What will be shown as "Category" on the view will be asked with the role CategoryDisplayRole.

## Member Function Documentation

## ◆ compareCategories()

int Digikam::DCategorizedSortFilterProxyModel::compareCategories | ( | const QModelIndex & | left,
|  | const QModelIndex & | right
| ) |  | const
| protectedvirtual

Internally and if not reimplemented, this method will ask for `left` and `right` models for role CategorySortRole. In order to correctly sort categories, the data() method of the model should return a qlonglong (or numeric) value, or a QString object. QString objects will be sorted with QString::localeAwareCompare if sortCategoriesByNaturalComparison() is true.

Note
  Please have present that: QString(QChar(QChar::ObjectReplacementCharacter)) > QString(QChar(QChar::ReplacementCharacter)) > [ all possible strings ] > QString();

This means that QString() will be sorted the first one, while QString(QChar(QChar::ObjectReplacementCharacter)) and QString(QChar(QChar::ReplacementCharacter)) will be sorted in last position.

Warning
  Please note that data() method of the model should return always information of the same type. If you return a QString for an index, you should return always QStrings for all indexes for role CategorySortRole in order to correctly sort categories. You cannot mix by returning a QString for one index, and a qlonglong for other.

Note
  If you need a more complex layout, you will have to reimplement this method.

Returns
  A negative value if the category of `left` should be placed before the category of `right`. 0 if `left` and `right` are on the same category, and a positive value if the category of `left` should be placed after the category of `right`.

Reimplemented in Digikam::ItemFilterModel, ShowFoto::ShowfotoFilterModel, and Digikam::ImportFilterModel.

## ◆ isCategorizedModel()

bool Digikam::DCategorizedSortFilterProxyModel::isCategorizedModel | ( |  | ) | const

Returns
  whether the model is categorized or not. Disabled by default.

## ◆ lessThan()

bool Digikam::DCategorizedSortFilterProxyModel::lessThan | ( | const QModelIndex & | left,
|  | const QModelIndex & | right
| ) |  | const
| overrideprotected

If you are subclassing DCategorizedSortFilterProxyModel, you will probably not need to reimplement this method.

It calls compareCategories() to sort by category. If the both items are in the same category (i.e. compareCategories returns 0), then subSortLessThan is called.

Returns
  Returns true if the item `left` is less than the item `right` when sorting.

Warning
  You usually won't need to reimplement this method when subclassing from DCategorizedSortFilterProxyModel.

## ◆ setCategorizedModel()

void Digikam::DCategorizedSortFilterProxyModel::setCategorizedModel | ( | bool | categorizedModel | ) |

Parameters

  categorizedModel | whether to enable or disable the categorization feature.

## ◆ setSortCategoriesByNaturalComparison()

void Digikam::DCategorizedSortFilterProxyModel::setSortCategoriesByNaturalComparison | ( | bool | sortCategoriesByNaturalComparison | ) |

If enabled, QCollator will be used for sorting.

Parameters

  sortCategoriesByNaturalComparison | whether to sort using a natural comparison or not.

## ◆ sort()

void Digikam::DCategorizedSortFilterProxyModel::sort | ( | int | column,
|  | Qt::SortOrder | order = `Qt::AscendingOrder`
| ) |  |
| override

Sorts the source model using `column` for the given `order`.

## ◆ sortCategoriesByNaturalComparison()

bool Digikam::DCategorizedSortFilterProxyModel::sortCategoriesByNaturalComparison | ( |  | ) | const

Returns
  whether it is being used a natural comparison for sorting. Enabled by default.

## ◆ sortColumn()

int Digikam::DCategorizedSortFilterProxyModel::sortColumn | ( |  | ) | const

Returns
  the column being used for sorting.

## ◆ sortOrder()

Qt::SortOrder Digikam::DCategorizedSortFilterProxyModel::sortOrder | ( |  | ) | const

Returns
  the sort order being used for sorting.

## ◆ subSortLessThan()

bool Digikam::DCategorizedSortFilterProxyModel::subSortLessThan | ( | const QModelIndex & | left,
|  | const QModelIndex & | right
| ) |  | const
| protectedvirtual

It is used for sorting items that are in the same category.

Returns
  Returns true if the item `left` is less than the item `right` when sorting.

Reimplemented in Digikam::ItemFilterModel, ShowFoto::ShowfotoFilterModel, and Digikam::ImportFilterModel.