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 KPAGEWIDGET_H
9 #define KPAGEWIDGET_H
10 
11 #include <kpagewidgetmodel.h>
12 
13 #include "kpageview.h"
14 
15 class KPageWidgetPrivate;
16 /**
17  * @class KPageWidget kpagewidget.h KPageWidget
18  *
19  * @short Page widget with many layouts (faces).
20  * A KPageView with hierarchical page model.
21  *
22  * @author Tobias Koenig (tokoe@kde.org)
23  */
24 class KWIDGETSADDONS_EXPORT KPageWidget : public KPageView
25 {
26     Q_OBJECT
27     Q_DECLARE_PRIVATE(KPageWidget)
28 
29 public:
30     /**
31      * Creates a new page widget.
32      *
33      * @param parent The parent widget.
34      */
35     explicit KPageWidget(QWidget *parent = nullptr);
36 
37     /**
38      * Destroys the page widget.
39      */
40     ~KPageWidget() override;
41 
42     /**
43      * Adds a new top level page to the widget.
44      *
45      * @param widget The widget of the page.
46      * @param name The name which is displayed in the navigation view.
47      *
48      * @returns The associated KPageWidgetItem.
49      */
50     KPageWidgetItem *addPage(QWidget *widget, const QString &name);
51 
52     /**
53      * Adds a new top level page to the widget.
54      *
55      * @param item The KPageWidgetItem which describes the page.
56      */
57     void addPage(KPageWidgetItem *item);
58 
59     /**
60      * Inserts a new page in the widget.
61      *
62      * @param before The new page will be insert before this KPageWidgetItem
63      *               on the same level in hierarchy.
64      * @param widget The widget of the page.
65      * @param name The name which is displayed in the navigation view.
66      *
67      * @returns The associated KPageWidgetItem.
68      */
69     KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name);
70 
71     /**
72      * Inserts a new page in the widget.
73      *
74      * @param before The new page will be insert before this KPageWidgetItem
75      *               on the same level in hierarchy.
76      *
77      * @param item The KPageWidgetItem which describes the page.
78      */
79     void insertPage(KPageWidgetItem *before, KPageWidgetItem *item);
80 
81     /**
82      * Inserts a new sub page in the widget.
83      *
84      * @param parent The new page will be insert as child of this KPageWidgetItem.
85      * @param widget The widget of the page.
86      * @param name The name which is displayed in the navigation view.
87      *
88      * @returns The associated KPageWidgetItem.
89      */
90     KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name);
91 
92     /**
93      * Inserts a new sub page in the widget.
94      *
95      * @param parent The new page will be insert as child of this KPageWidgetItem.
96      *
97      * @param item The KPageWidgetItem which describes the page.
98      */
99     void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item);
100 
101     /**
102      * Removes the page associated with the given KPageWidgetItem.
103      */
104     void removePage(KPageWidgetItem *item);
105 
106     /**
107      * Sets the page which is associated with the given KPageWidgetItem to
108      * be the current page and emits the currentPageChanged() signal.
109      */
110     void setCurrentPage(KPageWidgetItem *item);
111 
112     /**
113      * Returns the KPageWidgetItem for the current page or a null pointer if there is no
114      * current page.
115      */
116     KPageWidgetItem *currentPage() const;
117 
118 Q_SIGNALS:
119     /**
120      * This signal is emitted whenever the current page has changed.
121      *
122      * @param current The new current page or a null pointer if no current page is available.
123      * @param before The page that was current before the new current page has changed.
124      */
125     void currentPageChanged(KPageWidgetItem *current, KPageWidgetItem *before);
126 
127     /**
128      * This signal is emitted whenever a checkable page changes its state. @param checked is true
129      * when the @p page is checked, or false if the @p page is unchecked.
130      */
131     void pageToggled(KPageWidgetItem *page, bool checked);
132 
133     /**
134      * This signal is emitted when a page is removed.
135      * @param page The page which is removed
136      * */
137     void pageRemoved(KPageWidgetItem *page);
138 
139 protected:
140     KPageWidget(KPageWidgetPrivate &dd, QWidget *parent);
141 };
142 
143 #endif
144