MauiKit Controls

mauimodel.h
1/*
2 * <one line to give the program's name and a brief idea of what it does.>
3 * Copyright (C) 2019 camilo <chiguitar@unal.edu.co>
4 *
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19#pragma once
20
21#include <QAbstractListModel>
22 #include <QQmlEngine>
23 #include <QObject>
24#include <QSortFilterProxyModel>
25
26#include "mauikit_export.h"
27
28class MauiList;
29
30/**
31 * @brief The MauiModel class.
32 *
33 * The MauiModel is a template model to be uses with MauiList, it aims to be a simple data model to quickly setup string based models using the FMH::MODEL_LIST and FMH::MODEL_KEY types.
34 *
35 * @note This class is exposed as the type `BaseModel` to the QML engine.
36 *
37 * @code
38 * Maui.BaseModel
39 * {
40 *
41 * }
42 * @endcode
43 *
44 * The idea is that the sorting and filtering is independent to the data list - MauiList.
45 * Now, to get the right items keep in mind: MauiList::get() gets the item at the original list index, while MauiModel::get() will get the item at the model index, if it is filtered or sorted, then that's the item you'd get.
46 *
47 * If you want to get a item from the source list and the model has been filtered or sorted you will need to use the MauiModel::mappedToSource() to map the index to the right index from the source list.
48 *
49 * Now, if you have a index from the source list and the model has been filtered or ordered you will use MauiModel::mappedFromSource() to get the right index from the model.
50 *
51 * <a href="https://invent.kde.org/maui/mauikit/-/blob/qt6-2/examples/mauilist/">You can find a more complete example at this link.</a>
52*/
53class MAUIKIT_EXPORT MauiModel : public QSortFilterProxyModel
54{
56 QML_NAMED_ELEMENT(BaseModel)
57 Q_DISABLE_COPY(MauiModel)
58
59 /*
60 * The data list to be consumed by the model. All the operations and features of this class depend on having an actual MauiList to act upon.
61 * @see MauiList
62 */
63 Q_PROPERTY(MauiList *list READ getList WRITE setList NOTIFY listChanged)
64
65 /*
66 * A single filter string. To clear the filter just set it to a empty string or invoke the `clearFilters()`method.
67 * @see clearFilters
68 */
69 Q_PROPERTY(QString filter READ getFilter WRITE setFilter NOTIFY filterChanged)
70
71 /*
72 * Multiple filtering strings.
73 * @see clearFilters
74 */
75 Q_PROPERTY(QStringList filters READ getFilters WRITE setFilters NOTIFY filtersChanged)
76
77 /*
78 * The key to be used for filtering. The sort keys can be found in the FMH::MODEL_NAME map of keys.
79 * For example, to filter by `FMH::MODEL_KEY::TITLE`, use `"title"`.
80 */
81 Q_PROPERTY(QString filterRole READ getFilterRoleName WRITE setFilterRoleName NOTIFY filterRoleNameChanged)
82
83 /*
84 * The sorting order.
85 * By default the list is unsorted.
86 * @see Qt::SortOrder
87 */
88 Q_PROPERTY(Qt::SortOrder sortOrder READ getSortOrder WRITE setSortOrder NOTIFY sortOrderChanged)
89
90 /*
91 * The sorting key value. The sort keys can be found in the FMH::MODEL_NAME map of keys.
92 */
93 Q_PROPERTY(QString sort READ getSort WRITE setSort NOTIFY sortChanged)
94
95 /*
96 * The total amount fo elements in the model.
97 */
98 Q_PROPERTY(int count READ count NOTIFY countChanged FINAL)
99
100public:
101 MauiModel(QObject *parent = nullptr);
102
103 MauiList *getList() const;
104
105 void setList(MauiList *);
106
107 Qt::SortOrder getSortOrder() const;
108 QString getSort() const;
109
110 const QString getFilter() const;
111 const QStringList getFilters() const;
112
113 QString getFilterRoleName() const;
114
115 int count() const;
116
117 bool moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild) override;
118 bool moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild);
119
120protected:
121 bool filterAcceptsRow(int, const QModelIndex &) const override;
122
123private:
124 class PrivateAbstractListModel;
125 PrivateAbstractListModel *m_model;
126 MauiList *m_list;
127
128 QString m_filter;
129 QStringList m_filters;
130 QString m_filterRoleName;
131 Qt::SortOrder m_sortOrder;
132 QString m_sort;
133
134public Q_SLOTS:
135
136 void setFilter(const QString &filter);
137 void setFilters(const QStringList &filters);
138
139 void setSortOrder(const Qt::SortOrder &sortOrder);
140
141 void setSort(const QString &sort);
142
143 /**
144 * @brief Returns an item in the model. This method correctly maps the given index in case the model has been sorted or filtered.
145 * @param index the position index of the item in the list
146 * @return a convenient QVariantMap that can be parsed on QML easily
147 */
148 QVariantMap get(const int &index) const;
149
150 /**
151 * @brief Returns all the items in the list represented as a QVariantList to be able to be used in QML. This operation performs a transformation from FMH::MODEL_LIST to QVariantList
152 * @return all the items in the list
153 */
154 QVariantList getAll() const;
155
156 /**
157 * @brief Maps a given index from the base list to the model, in case the model has been filtered or sorted, this gives you the right mapped index
158 * @param index the original position index in the list
159 * @return the mapped index in the model
160 */
161 int mappedFromSource(const int &index) const;
162
163 /**
164 * @brief Given an index from the filtered or sorted model it returns the mapped index to the original list index.
165 * @param index the model index
166 * @return the original position index in the list
167 */
168 int mappedToSource(const int &) const;
169
170 void setFilterRoleName(QString );
171 bool move(const int &index, const int &to);
172
173 /**
174 * @brief Restores the model if filtered, and clears all the filters set with the `filter` and `filters` properties.
175 */
176 void clearFilters();
177
179 void listChanged();
180 void filterChanged(QString);
181 void filtersChanged(QStringList);
182 void sortOrderChanged(Qt::SortOrder);
183 void sortChanged(QString);
184 void filterRoleNameChanged(QString);
185 void countChanged();
186};
187
188/**
189 * @private
190 */
191class MauiModel::PrivateAbstractListModel : public QAbstractListModel
192{
194 Q_DISABLE_COPY(PrivateAbstractListModel)
195
196public:
197 PrivateAbstractListModel(MauiModel *);
198 int rowCount(const QModelIndex & = QModelIndex()) const override;
199
200 QVariant data(const QModelIndex &, int = Qt::DisplayRole) const override;
201
202 // Editable:
203 bool setData(const QModelIndex &, const QVariant &, int = Qt::EditRole) override;
204
205 Qt::ItemFlags flags(const QModelIndex &) const override;
206
207 virtual QHash<int, QByteArray> roleNames() const override;
208
209 void setUpList();
210
211 void reset();
212private:
213 MauiModel *m_model;
214};
MauiList class.
Definition mauilist.h:180
The MauiModel class.
Definition mauimodel.h:54
QVariantMap get(const int &index) const
Returns an item in the model.
Definition mauimodel.cpp:32
void clearFilters()
Restores the model if filtered, and clears all the filters set with the filter and filters properties...
Definition mauimodel.cpp:98
int mappedFromSource(const int &index) const
Maps a given index from the base list to the model, in case the model has been filtered or sorted,...
int mappedToSource(const int &) const
Given an index from the filtered or sorted model it returns the mapped index to the original list ind...
QVariantList getAll() const
Returns all the items in the list represented as a QVariantList to be able to be used in QML.
Definition mauimodel.cpp:45
Q_SCRIPTABLE bool setFilter(const QString &filter)
bool moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)
virtual bool moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
QSortFilterProxyModel(QObject *parent)
virtual bool filterAcceptsRow(int source_row, const QModelIndex &source_parent) const const
virtual QModelIndex index(int row, int column, const QModelIndex &parent) const const override
virtual QModelIndex parent(const QModelIndex &child) const const override
DisplayRole
typedef ItemFlags
SortOrder
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri May 2 2025 11:57:11 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.