KWidgetsAddons

kpagewidgetmodel.h
1 /*
2  This file is part of the KDE Libraries
3  SPDX-FileCopyrightText: 2006 Tobias Koenig <[email protected]>
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 ([email protected])
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
Q_PROPERTY(...)
DisplayRole
A base class for a model used by KPageView.
Definition: kpagemodel.h:46
typedef ItemFlags
Q_SIGNALSQ_SIGNALS
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Dec 1 2023 04:04:13 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.