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;
15class QAction;
16
17/*!
18 * \class KPageWidgetItem
19 * \inmodule KWidgetsAddons
20 * \inheaderfile KPageWidgetModel
21 *
22 * \brief KPageWidgetItem is used by KPageWidget and represents
23 * a page.
24 *
25 * Example:
26 *
27 * \code
28 * ColorPage *page = new ColorPage;
29 *
30 * KPageWidgetItem *item = new KPageWidgetItem( page, i18n( "Colors" ) );
31 * item->setHeader( i18n( "Colors of Main Window" ) );
32 * item->setIcon( QIcon::fromTheme( "colors" ) );
33 *
34 * KPageWidget *pageWidget = new KPageWidget( this );
35 * pageWidget->addPage( item );
36 * \endcode
37 */
38class KWIDGETSADDONS_EXPORT KPageWidgetItem : public QObject
39{
40 Q_OBJECT
41
42 /*!
43 * \property KPageWidgetItem::name
44 */
45 Q_PROPERTY(QString name READ name WRITE setName)
46
47 /*!
48 * \property KPageWidgetItem::header
49 */
50 Q_PROPERTY(QString header READ header WRITE setHeader)
51
52 /*!
53 * \property KPageWidgetItem::icon
54 */
55 Q_PROPERTY(QIcon icon READ icon WRITE setIcon)
56
57 /*!
58 * \property KPageWidgetItem::checkable
59 */
60 Q_PROPERTY(bool checkable READ isCheckable WRITE setCheckable)
61
62 /*!
63 * \property KPageWidgetItem::checked
64 */
65 Q_PROPERTY(bool checked READ isChecked WRITE setChecked)
66
67 /*!
68 * \property KPageWidgetItem::enabled
69 *
70 * This property holds whether the item is enabled.
71 *
72 * It dis-/enables both the widget and the item in the list-/treeview.
73 */
74 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled)
75
76 /*!
77 * \property KPageWidgetItem::headerVisible
78 * \since 5.52
79 */
80 Q_PROPERTY(bool headerVisible READ isHeaderVisible WRITE setHeaderVisible)
81
82 /*!
83 * \property KPageWidgetItem::actions
84 *
85 * This property holds the actions associated to the page.
86 *
87 * \warning This is not supported when using a KPageView/KPageWidget/KPageDialog with
88 * the Tabbed face type.
89 * \since 6.6
90 */
91 Q_PROPERTY(QList<QAction *> actions READ actions WRITE setActions NOTIFY actionsChanged)
92public:
93 /*!
94 * Creates a new page widget item.
95 *
96 * \a widget The widget that is shown as page in the KPageWidget.
97 */
98 KPageWidgetItem(QWidget *widget);
99
100 /*!
101 * Creates a new page widget item.
102 *
103 * \a widget The widget that is shown as page in the KPageWidget.
104 *
105 * \a name The localized string that is show in the navigation view
106 * of the KPageWidget.
107 */
108 KPageWidgetItem(QWidget *widget, const QString &name);
109
110 ~KPageWidgetItem() override;
111
112 /*!
113 * Returns the widget of the page widget item.
114 */
115 QWidget *widget() const;
116
117 /*!
118 * Sets the name of the item as shown in the navigation view of the page
119 * widget.
120 */
121 void setName(const QString &name);
122
123 /*!
124 * Returns the name of the page widget item.
125 */
126 QString name() const;
127
128 /*!
129 * Sets the header of the page widget item.
130 *
131 * If setHeader(QString()) is used, what is the default if the header
132 * does not got set explicit, then the defined name() will also be used
133 * for the header.
134 *
135 * \a header Header of the page widget item.
136 */
137 void setHeader(const QString &header);
138
139 /*!
140 * Returns the header of the page widget item.
141 */
142 QString header() const;
143
144 /*!
145 * Sets the icon of the page widget item.
146 * \a icon Icon of the page widget item.
147 */
148 void setIcon(const QIcon &icon);
149
150 /*!
151 * Returns the icon of the page widget item.
152 */
153 QIcon icon() const;
154
155 /*!
156 * Sets whether the page widget item is checkable in the view.
157 * \a checkable True if the page widget is checkable,
158 * otherwise false.
159 */
160 void setCheckable(bool checkable);
161
162 /*!
163 * Returns whether the page widget item is checkable.
164 */
165 bool isCheckable() const;
166
167 /*!
168 * Returns whether the page widget item is checked.
169 */
170 bool isChecked() const;
171
172 /*!
173 * Returns whether the page widget item is enabled.
174 */
175 bool isEnabled() const;
176
177 /*!
178 * Returns whether the page will show the header title
179 * \since 5.52
180 */
181 bool isHeaderVisible() const;
182
183 /*!
184 * Set whether the page should show the header title
185 * \since 5.52
186 */
187 void setHeaderVisible(bool visible);
188
189 /*!
190 * Returns the actions associated to the page.
191 * \since 6.6
192 */
193 QList<QAction *> actions() const;
194
195 /*!
196 * Set the actions associated to the page.
197 * \since 6.6
198 */
199 void setActions(QList<QAction *> actions);
200
201public Q_SLOTS:
202 /*!
203 * Sets whether the page widget item is enabled.
204 */
205 void setEnabled(bool);
206
207 /*!
208 * Sets whether the page widget item is checked.
209 */
210 void setChecked(bool checked);
211
212Q_SIGNALS:
213 /*!
214 * This signal is emitted whenever the icon or header
215 * is changed.
216 */
217 void changed();
218
219 /*!
220 * This signal is emitted whenever the user checks or
221 * unchecks the item of setChecked() is called.
222 */
223 void toggled(bool checked);
224
225 /*!
226 * This signal is emitted whenever the actions associated to the
227 * page are changed.
228 * \since 6.6
229 */
230 void actionsChanged();
231
232private:
233 std::unique_ptr<class KPageWidgetItemPrivate> const d;
234};
235
236class KPageWidgetModelPrivate;
237
238/*!
239 * \class KPageWidgetModel
240 * \inmodule KWidgetsAddons
241 *
242 * \brief This page model is used by KPageWidget to provide
243 * a hierarchical layout of pages.
244 */
245class KWIDGETSADDONS_EXPORT KPageWidgetModel : public KPageModel
246{
247 Q_OBJECT
248 Q_DECLARE_PRIVATE(KPageWidgetModel)
249
250public:
251 /*!
252 * Creates a new page widget model.
253 *
254 * \a parent The parent object.
255 */
256 explicit KPageWidgetModel(QObject *parent = nullptr);
257
258 /*!
259 * Destroys the page widget model.
260 */
261 ~KPageWidgetModel() override;
262
263 /*!
264 * Adds a new top level page to the model.
265 *
266 * \a widget The widget of the page.
267 *
268 * \a name The name which is displayed in the navigation view.
269 *
270 * Returns the associated KPageWidgetItem.
271 */
272 KPageWidgetItem *addPage(QWidget *widget, const QString &name);
273
274 /*!
275 * Adds a new top level page to the model.
276 *
277 * \a item The KPageWidgetItem which describes the page.
278 */
279 void addPage(KPageWidgetItem *item);
280
281 /*!
282 * Inserts a new page in the model.
283 *
284 * \a before The new page will be insert before this KPageWidgetItem
285 * on the same level in hierarchy.
286 * \a widget The widget of the page.
287 *
288 * \a name The name which is displayed in the navigation view.
289 *
290 * Returns the associated KPageWidgetItem.
291 */
292 KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name);
293
294 /*!
295 * Inserts a new page in the model.
296 *
297 * \a before The new page will be insert before this KPageWidgetItem
298 * on the same level in hierarchy.
299 *
300 * \a item The KPageWidgetItem which describes the page.
301 */
302 void insertPage(KPageWidgetItem *before, KPageWidgetItem *item);
303
304 /*!
305 * Inserts a new sub page in the model.
306 *
307 * \a parent The new page will be insert as child of this KPageWidgetItem.
308 *
309 * \a widget The widget of the page.
310 *
311 * \a name The name which is displayed in the navigation view.
312 *
313 * Returns the associated KPageWidgetItem.
314 */
315 KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name);
316
317 /*!
318 * Inserts a new sub page in the model.
319 *
320 * \a parent The new page will be insert as child of this KPageWidgetItem.
321 *
322 * \a item The KPageWidgetItem which describes the page.
323 */
324 void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item);
325
326 /*!
327 * Removes the page associated with the given KPageWidgetItem.
328 */
329 void removePage(KPageWidgetItem *item);
330
331 int columnCount(const QModelIndex &parent = QModelIndex()) const override;
332 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
333 bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override;
334 Qt::ItemFlags flags(const QModelIndex &index) const override;
335 QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override;
336 QModelIndex parent(const QModelIndex &index) const override;
337 int rowCount(const QModelIndex &parent = QModelIndex()) const override;
338
339 /*!
340 * Returns the KPageWidgetItem for a given index or a null pointer if the index is invalid.
341 */
342 KPageWidgetItem *item(const QModelIndex &index) const;
343
344 /*!
345 * Returns the index for a given KPageWidgetItem. The index is invalid if the
346 * item can't be found in the model.
347 */
348 QModelIndex index(const KPageWidgetItem *item) const;
349
350Q_SIGNALS:
351 /*!
352 * This signal is emitted whenever a checkable page changes its state. \a checked is true
353 * when the \a page is checked, or false if the \a page is unchecked.
354 */
355 void toggled(KPageWidgetItem *page, bool checked);
356
357private:
358 Q_PRIVATE_SLOT(d_func(), void _k_itemChanged())
359 Q_PRIVATE_SLOT(d_func(), void _k_itemToggled(bool))
360};
361
362#endif
363

source code of kwidgetsaddons/src/kpagewidgetmodel.h