KWidgetsAddons

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

KDE's Doxygen guidelines are available online.