1/*
2 This file is part of the KDE Libraries
3 SPDX-FileCopyrightText: 2006 Tobias Koenig <tokoe@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPAGEWIDGETMODEL_H
9#define KPAGEWIDGETMODEL_H
10
11#include "kpagemodel.h"
12#include <memory>
13
14class QWidget;
15
16/**
17 * @class KPageWidgetItem kpagewidgetmodel.h KPageWidgetItem
18 *
19 * KPageWidgetItem is used by @ref KPageWidget and represents
20 * a page.
21 *
22 * <b>Example:</b>\n
23 *
24 * \code
25 * ColorPage *page = new ColorPage;
26 *
27 * KPageWidgetItem *item = new KPageWidgetItem( page, i18n( "Colors" ) );
28 * item->setHeader( i18n( "Colors of Main Window" ) );
29 * item->setIcon( QIcon::fromTheme( "colors" ) );
30 *
31 * KPageWidget *pageWidget = new KPageWidget( this );
32 * pageWidget->addPage( item );
33 * \endcode
34 *
35 * @author Tobias Koenig (tokoe@kde.org)
36 */
37class KWIDGETSADDONS_EXPORT KPageWidgetItem : public QObject
38{
39 Q_OBJECT
40 Q_PROPERTY(QString name READ name WRITE setName)
41 Q_PROPERTY(QString header READ header WRITE setHeader)
42 Q_PROPERTY(QIcon icon READ icon WRITE setIcon)
43 Q_PROPERTY(bool checkable READ isCheckable WRITE setCheckable)
44 Q_PROPERTY(bool checked READ isChecked WRITE setChecked)
45 /**
46 * This property holds whether the item is enabled.
47 *
48 * It dis-/enables both the widget and the item in the list-/treeview.
49 */
50 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled)
51 /**
52 * @since 5.52
53 */
54 Q_PROPERTY(bool headerVisible READ isHeaderVisible WRITE setHeaderVisible)
55public:
56 /**
57 * Creates a new page widget item.
58 *
59 * @param widget The widget that is shown as page in the KPageWidget.
60 */
61 KPageWidgetItem(QWidget *widget);
62
63 /**
64 * Creates a new page widget item.
65 *
66 * @param widget The widget that is shown as page in the KPageWidget.
67 * @param name The localized string that is show in the navigation view
68 * of the KPageWidget.
69 */
70 KPageWidgetItem(QWidget *widget, const QString &name);
71
72 /**
73 * Destroys the page widget item.
74 */
75 ~KPageWidgetItem() override;
76
77 /**
78 * Returns the widget of the page widget item.
79 */
80 QWidget *widget() const;
81
82 /**
83 * Sets the name of the item as shown in the navigation view of the page
84 * widget.
85 */
86 void setName(const QString &name);
87
88 /**
89 * Returns the name of the page widget item.
90 */
91 QString name() const;
92
93 /**
94 * Sets the header of the page widget item.
95 *
96 * If setHeader(QString()) is used, what is the default if the header
97 * does not got set explicit, then the defined name() will also be used
98 * for the header.
99 *
100 * @param header Header of the page widget item.
101 */
102 void setHeader(const QString &header);
103
104 /**
105 * Returns the header of the page widget item.
106 */
107 QString header() const;
108
109 /**
110 * Sets the icon of the page widget item.
111 * @param icon Icon of the page widget item.
112 */
113 void setIcon(const QIcon &icon);
114
115 /**
116 * Returns the icon of the page widget item.
117 */
118 QIcon icon() const;
119
120 /**
121 * Sets whether the page widget item is checkable in the view.
122 * @param checkable True if the page widget is checkable,
123 * otherwise false.
124 */
125 void setCheckable(bool checkable);
126
127 /**
128 * Returns whether the page widget item is checkable.
129 */
130 bool isCheckable() const;
131
132 /**
133 * Returns whether the page widget item is checked.
134 */
135 bool isChecked() const;
136
137 /**
138 * Returns whether the page widget item is enabled.
139 */
140 bool isEnabled() const;
141
142 /**
143 * Returns whether the page will show the header title
144 * @since 5.52
145 */
146 bool isHeaderVisible() const;
147
148 /**
149 * Set whether the page should show the header title
150 * @since 5.52
151 */
152 void setHeaderVisible(bool visible);
153
154public Q_SLOTS:
155 /**
156 * Sets whether the page widget item is enabled.
157 */
158 void setEnabled(bool);
159
160 /**
161 * Sets whether the page widget item is checked.
162 */
163 void setChecked(bool checked);
164
165Q_SIGNALS:
166 /**
167 * This signal is emitted whenever the icon or header
168 * is changed.
169 */
170 void changed();
171
172 /**
173 * This signal is emitted whenever the user checks or
174 * unchecks the item of setChecked() is called.
175 */
176 void toggled(bool checked);
177
178private:
179 std::unique_ptr<class KPageWidgetItemPrivate> const d;
180};
181
182class KPageWidgetModelPrivate;
183
184/**
185 * @class KPageWidgetModel kpagewidgetmodel.h KPageWidgetModel
186 *
187 * This page model is used by KPageWidget to provide
188 * a hierarchical layout of pages.
189 */
190class KWIDGETSADDONS_EXPORT KPageWidgetModel : public KPageModel
191{
192 Q_OBJECT
193 Q_DECLARE_PRIVATE(KPageWidgetModel)
194
195public:
196 /**
197 * Creates a new page widget model.
198 *
199 * @param parent The parent object.
200 */
201 explicit KPageWidgetModel(QObject *parent = nullptr);
202
203 /**
204 * Destroys the page widget model.
205 */
206 ~KPageWidgetModel() override;
207
208 /**
209 * Adds a new top level page to the model.
210 *
211 * @param widget The widget of the page.
212 * @param name The name which is displayed in the navigation view.
213 *
214 * @returns The associated KPageWidgetItem.
215 */
216 KPageWidgetItem *addPage(QWidget *widget, const QString &name);
217
218 /**
219 * Adds a new top level page to the model.
220 *
221 * @param item The KPageWidgetItem which describes the page.
222 */
223 void addPage(KPageWidgetItem *item);
224
225 /**
226 * Inserts a new page in the model.
227 *
228 * @param before The new page will be insert before this KPageWidgetItem
229 * on the same level in hierarchy.
230 * @param widget The widget of the page.
231 * @param name The name which is displayed in the navigation view.
232 *
233 * @returns The associated KPageWidgetItem.
234 */
235 KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name);
236
237 /**
238 * Inserts a new page in the model.
239 *
240 * @param before The new page will be insert before this KPageWidgetItem
241 * on the same level in hierarchy.
242 *
243 * @param item The KPageWidgetItem which describes the page.
244 */
245 void insertPage(KPageWidgetItem *before, KPageWidgetItem *item);
246
247 /**
248 * Inserts a new sub page in the model.
249 *
250 * @param parent The new page will be insert as child of this KPageWidgetItem.
251 * @param widget The widget of the page.
252 * @param name The name which is displayed in the navigation view.
253 *
254 * @returns The associated KPageWidgetItem.
255 */
256 KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name);
257
258 /**
259 * Inserts a new sub page in the model.
260 *
261 * @param parent The new page will be insert as child of this KPageWidgetItem.
262 *
263 * @param item The KPageWidgetItem which describes the page.
264 */
265 void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item);
266
267 /**
268 * Removes the page associated with the given KPageWidgetItem.
269 */
270 void removePage(KPageWidgetItem *item);
271
272 /**
273 * These methods are reimplemented from QAbstractItemModel.
274 */
275 int columnCount(const QModelIndex &parent = QModelIndex()) const override;
276 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
277 bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override;
278 Qt::ItemFlags flags(const QModelIndex &index) const override;
279 QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override;
280 QModelIndex parent(const QModelIndex &index) const override;
281 int rowCount(const QModelIndex &parent = QModelIndex()) const override;
282
283 /**
284 * Returns the KPageWidgetItem for a given index or a null pointer if the index is invalid.
285 */
286 KPageWidgetItem *item(const QModelIndex &index) const;
287
288 /**
289 * Returns the index for a given KPageWidgetItem. The index is invalid if the
290 * item can't be found in the model.
291 */
292 QModelIndex index(const KPageWidgetItem *item) const;
293
294Q_SIGNALS:
295 /**
296 * This signal is emitted whenever a checkable page changes its state. @param checked is true
297 * when the @p page is checked, or false if the @p page is unchecked.
298 */
299 void toggled(KPageWidgetItem *page, bool checked);
300
301private:
302 Q_PRIVATE_SLOT(d_func(), void _k_itemChanged())
303 Q_PRIVATE_SLOT(d_func(), void _k_itemToggled(bool))
304};
305
306#endif
307

source code of kwidgetsaddons/src/kpagewidgetmodel.h