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 
14 class 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  */
37 class 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)
55 public:
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      * For backward-compatibility, if setHeader("") is used, the header will be hidden
101      * even if the @a KPageView::FaceType is something else then Tabbed.
102      * This feature is deprecated since 5.52. use @c setHeaderVisible(false) instead.
103      *
104      * @param header Header of the page widget item.
105      */
106     void setHeader(const QString &header);
107 
108     /**
109      * Returns the header of the page widget item.
110      */
111     QString header() const;
112 
113     /**
114      * Sets the icon of the page widget item.
115      * @param icon Icon of the page widget item.
116      */
117     void setIcon(const QIcon &icon);
118 
119     /**
120      * Returns the icon of the page widget item.
121      */
122     QIcon icon() const;
123 
124     /**
125      * Sets whether the page widget item is checkable in the view.
126      * @param checkable True if the page widget is checkable,
127      *                  otherwise false.
128      */
129     void setCheckable(bool checkable);
130 
131     /**
132      * Returns whether the page widget item is checkable.
133      */
134     bool isCheckable() const;
135 
136     /**
137      * Returns whether the page widget item is checked.
138      */
139     bool isChecked() const;
140 
141     /**
142      * Returns whether the page widget item is enabled.
143      */
144     bool isEnabled() const;
145 
146     /**
147      * Returns whether the page will show the header title
148      * @since 5.52
149      */
150     bool isHeaderVisible() const;
151 
152     /**
153      * Set whether the page should show the header title
154      * @since 5.52
155      */
156     void setHeaderVisible(bool visible);
157 
158 public Q_SLOTS:
159     /**
160      * Sets whether the page widget item is enabled.
161      */
162     void setEnabled(bool);
163 
164     /**
165      * Sets whether the page widget item is checked.
166      */
167     void setChecked(bool checked);
168 
169 Q_SIGNALS:
170     /**
171      * This signal is emitted whenever the icon or header
172      * is changed.
173      */
174     void changed();
175 
176     /**
177      * This signal is emitted whenever the user checks or
178      * unchecks the item of setChecked() is called.
179      */
180     void toggled(bool checked);
181 
182 private:
183     std::unique_ptr<class KPageWidgetItemPrivate> const d;
184 };
185 
186 class KPageWidgetModelPrivate;
187 
188 /**
189  * @class KPageWidgetModel kpagewidgetmodel.h KPageWidgetModel
190  *
191  * This page model is used by KPageWidget to provide
192  * a hierarchical layout of pages.
193  */
194 class KWIDGETSADDONS_EXPORT KPageWidgetModel : public KPageModel
195 {
196     Q_OBJECT
197     Q_DECLARE_PRIVATE(KPageWidgetModel)
198 
199 public:
200     /**
201      * Creates a new page widget model.
202      *
203      * @param parent The parent object.
204      */
205     explicit KPageWidgetModel(QObject *parent = nullptr);
206 
207     /**
208      * Destroys the page widget model.
209      */
210     ~KPageWidgetModel() override;
211 
212     /**
213      * Adds a new top level page to the model.
214      *
215      * @param widget The widget of the page.
216      * @param name The name which is displayed in the navigation view.
217      *
218      * @returns The associated KPageWidgetItem.
219      */
220     KPageWidgetItem *addPage(QWidget *widget, const QString &name);
221 
222     /**
223      * Adds a new top level page to the model.
224      *
225      * @param item The KPageWidgetItem which describes the page.
226      */
227     void addPage(KPageWidgetItem *item);
228 
229     /**
230      * Inserts a new page in the model.
231      *
232      * @param before The new page will be insert before this KPageWidgetItem
233      *               on the same level in hierarchy.
234      * @param widget The widget of the page.
235      * @param name The name which is displayed in the navigation view.
236      *
237      * @returns The associated KPageWidgetItem.
238      */
239     KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name);
240 
241     /**
242      * Inserts a new page in the model.
243      *
244      * @param before The new page will be insert before this KPageWidgetItem
245      *               on the same level in hierarchy.
246      *
247      * @param item The KPageWidgetItem which describes the page.
248      */
249     void insertPage(KPageWidgetItem *before, KPageWidgetItem *item);
250 
251     /**
252      * Inserts a new sub page in the model.
253      *
254      * @param parent The new page will be insert as child of this KPageWidgetItem.
255      * @param widget The widget of the page.
256      * @param name The name which is displayed in the navigation view.
257      *
258      * @returns The associated KPageWidgetItem.
259      */
260     KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name);
261 
262     /**
263      * Inserts a new sub page in the model.
264      *
265      * @param parent The new page will be insert as child of this KPageWidgetItem.
266      *
267      * @param item The KPageWidgetItem which describes the page.
268      */
269     void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item);
270 
271     /**
272      * Removes the page associated with the given KPageWidgetItem.
273      */
274     void removePage(KPageWidgetItem *item);
275 
276     /**
277      * These methods are reimplemented from QAbstractItemModel.
278      */
279     int columnCount(const QModelIndex &parent = QModelIndex()) const override;
280     QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
281     bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override;
282     Qt::ItemFlags flags(const QModelIndex &index) const override;
283     QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override;
284     QModelIndex parent(const QModelIndex &index) const override;
285     int rowCount(const QModelIndex &parent = QModelIndex()) const override;
286 
287     /**
288      * Returns the KPageWidgetItem for a given index or a null pointer if the index is invalid.
289      */
290     KPageWidgetItem *item(const QModelIndex &index) const;
291 
292     /**
293      * Returns the index for a given KPageWidgetItem. The index is invalid if the
294      * item can't be found in the model.
295      */
296     QModelIndex index(const KPageWidgetItem *item) const;
297 
298 Q_SIGNALS:
299     /**
300      * This signal is emitted whenever a checkable page changes its state. @param checked is true
301      * when the @p page is checked, or false if the @p page is unchecked.
302      */
303     void toggled(KPageWidgetItem *page, bool checked);
304 
305 private:
306     Q_PRIVATE_SLOT(d_func(), void _k_itemChanged())
307     Q_PRIVATE_SLOT(d_func(), void _k_itemToggled(bool))
308 };
309 
310 #endif
311