1/*
2 This file is part of the KDE Libraries
3 SPDX-FileCopyrightText: 1999-2001 Mirko Boehm <mirko@kde.org>
4 SPDX-FileCopyrightText: 1999-2001 Espen Sand <espen@kde.org>
5 SPDX-FileCopyrightText: 1999-2001 Holger Freyther <freyther@kde.org>
6 SPDX-FileCopyrightText: 2005-2006 Olivier Goffart <ogoffart at kde.org>
7 SPDX-FileCopyrightText: 2006 Tobias Koenig <tokoe@kde.org>
8
9 SPDX-License-Identifier: LGPL-2.0-or-later
10*/
11#ifndef KPAGEDIALOG_H
12#define KPAGEDIALOG_H
13
14#include <QDialog>
15#include <QDialogButtonBox>
16#include <kpagewidget.h>
17#include <memory>
18
19class KPageDialogPrivate;
20
21/**
22 * @class KPageDialog kpagedialog.h KPageDialog
23 *
24 * @short A dialog base class which can handle multiple pages.
25 *
26 * This class provides a dialog base class which handles multiple
27 * pages and allows the user to switch between these pages in
28 * different ways.
29 *
30 * Currently, @p Auto, @p Plain, @p List, @p Tree and @p Tabbed face
31 * types are available (cmp. KPageView).
32 *
33 * By default a QDialogButtonBox is added to the dialog with two buttons,
34 * OK (@c QDialogButtonBox::Ok) and Cancel (@c QDialogButtonBox::Cancel).
35 * You can customize which buttons are added to the dialog by using any of the
36 * available buttons-related methods.
37 *
38 * Note that if there is a QDialogButtonBox (either the one added by default, or
39 * one you added manually) some logical connections are created:
40 * - @c QDialogButtonBox::accepted() is connected to @c QDialog::accept()
41 * - @c QDialogButtonBox::rejected() is connected to @c QDialog::reject()
42 * this means that you shouldn't create these connections again (otherwise you
43 * would end up receiving two duplicate accepted() signals for example).
44 *
45 * <b>Example:</b>\n
46 *
47 * @code
48 * UrlDialog::UrlDialog( QWidget *parent )
49 * : KPageDialog( parent )
50 * {
51 * setFaceType(List);
52 *
53 * QLabel *label = new QLabel("Test Page");
54 * addPage(label, i18n("My Test Page"));
55 *
56 * label = new QLabel("Second Test Page");
57 * KPageWidgetItem *page = new KPageWidgetItem(label, i18n("My Second Test Page"));
58 * page->setHeader(i18n("My header string"));
59 * page->setIcon(QIcon::fromTheme("file"));
60 *
61 * addPage(page);
62 *
63 * // Change the buttons added to the dialog
64 * setStandardButtons(QDialogButtonBox::Ok | QDialogButtonBox::Apply | QDialogButtonBox::Cancel);
65 *
66 * // Alternatively you can create a QDialogButtonBox, add the buttons you want to it,
67 * // then add that button box to the dialog
68 * QDialogButtonBox *btnBox = new QDialogButtonBox(QDialogButtonBox::Ok | QDialogButtonBox::Apply | QDialogButtonBox::Cancel,
69 * Qt::Horizontal,
70 * this);
71 * setButtonBox(btnBox);
72 * }
73 * @endcode
74 *
75 * @author Tobias Koenig (tokoe@kde.org)
76 */
77class KWIDGETSADDONS_EXPORT KPageDialog : public QDialog
78{
79 Q_OBJECT
80 Q_DECLARE_PRIVATE(KPageDialog)
81
82public:
83 /**
84 * The face types supported.
85 */
86 enum FaceType {
87 /**
88 * A dialog with a face based on the structure of the available pages.
89 * If only a single page is added, the dialog behaves like
90 * in @c Plain mode, with multiple pages without sub pages
91 * it behaves like in @c List mode and like in @c Tree mode otherwise.
92 */
93 Auto = KPageView::Auto,
94 /**
95 * A normal dialog
96 */
97 Plain = KPageView::Plain,
98 /**
99 * A dialog with an icon list on the left side and a
100 * representation of the contents on the right side
101 */
102 List = KPageView::List,
103 /**
104 * A dialog with a tree on the left side and a
105 * representation of the contents on the right side
106 */
107 Tree = KPageView::Tree,
108 /**
109 * A dialog with a tab bar above the representation
110 * of the contents
111 */
112 Tabbed = KPageView::Tabbed,
113 /**
114 * A dialog with an flat list with small icons on the left side
115 * and a representation of the contents on the right side
116 */
117 FlatList = KPageView::FlatList,
118 };
119
120public:
121 /**
122 * Creates a new page dialog.
123 */
124 explicit KPageDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags());
125
126 /**
127 * Destroys the page dialog.
128 */
129 ~KPageDialog() override;
130
131 /**
132 * Sets the face type of the dialog.
133 */
134 void setFaceType(FaceType faceType);
135
136 /**
137 * Adds a new top level page to the dialog.
138 *
139 * @param widget The widget of the page.
140 * @param name The name which is displayed in the navigation view.
141 *
142 * @returns The associated KPageWidgetItem.
143 */
144 KPageWidgetItem *addPage(QWidget *widget, const QString &name);
145
146 /**
147 * Adds a new top level page to the dialog.
148 *
149 * @param item The KPageWidgetItem which describes the page.
150 */
151 void addPage(KPageWidgetItem *item);
152
153 /**
154 * Inserts a new page in the dialog.
155 *
156 * @param before The new page will be insert before this KPageWidgetItem
157 * on the same level in hierarchy.
158 * @param widget The widget of the page.
159 * @param name The name which is displayed in the navigation view.
160 *
161 * @returns The associated KPageWidgetItem.
162 */
163 KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name);
164
165 /**
166 * Inserts a new page in the dialog.
167 *
168 * @param before The new page will be insert before this KPageWidgetItem
169 * on the same level in hierarchy.
170 *
171 * @param item The KPageWidgetItem which describes the page.
172 */
173 void insertPage(KPageWidgetItem *before, KPageWidgetItem *item);
174
175 /**
176 * Inserts a new sub page in the dialog.
177 *
178 * @param parent The new page will be insert as child of this KPageWidgetItem.
179 * @param widget The widget of the page.
180 * @param name The name which is displayed in the navigation view.
181 *
182 * @returns The associated KPageWidgetItem.
183 */
184 KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name);
185
186 /**
187 * Inserts a new sub page in the dialog.
188 *
189 * @param parent The new page will be insert as child of this KPageWidgetItem.
190 *
191 * @param item The KPageWidgetItem which describes the page.
192 */
193 void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item);
194
195 /**
196 * Removes the page associated with the given KPageWidgetItem.
197 */
198 void removePage(KPageWidgetItem *item);
199
200 /**
201 * Sets the page which is associated with the given KPageWidgetItem to
202 * be the current page and emits the currentPageChanged() signal.
203 */
204 void setCurrentPage(KPageWidgetItem *item);
205
206 /**
207 * Returns the KPageWidgetItem for the current page or a null pointer if there is no
208 * current page.
209 */
210 KPageWidgetItem *currentPage() const;
211
212 /**
213 * Sets the collection of standard buttons displayed by this dialog.
214 */
215 void setStandardButtons(QDialogButtonBox::StandardButtons buttons);
216
217 /**
218 * Returns the QPushButton corresponding to the standard button which, or a null pointer if the standard
219 * button doesn't exist in this dialog.
220 */
221 QPushButton *button(QDialogButtonBox::StandardButton which) const;
222
223 /**
224 * Set an action button.
225 */
226 void addActionButton(QAbstractButton *button);
227
228Q_SIGNALS:
229 /**
230 * This signal is emitted whenever the current page has changed.
231 *
232 * @param current The new current page or a null pointer if no current page is available.
233 * @param before The page that was current before the new current page has changed.
234 */
235 void currentPageChanged(KPageWidgetItem *current, KPageWidgetItem *before);
236
237 /**
238 * This signal is emitted whenever a page has been removed.
239 *
240 * @param page The page which has been removed
241 */
242 void pageRemoved(KPageWidgetItem *page);
243
244protected:
245 /**
246 * This constructor can be used by subclasses to provide a custom page widget.
247 *
248 * \param widget The KPageWidget object will be reparented to this object, so you can create
249 * it without parent and you are not allowed to delete it.
250 */
251 KPageDialog(KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags());
252 KWIDGETSADDONS_NO_EXPORT KPageDialog(KPageDialogPrivate &dd, KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags());
253
254 /**
255 * Returns the page widget of the dialog or a null pointer if no page widget is set.
256 */
257 KPageWidget *pageWidget();
258
259 /**
260 * Returns the page widget of the dialog or a null pointer if no page widget is set.
261 */
262 const KPageWidget *pageWidget() const;
263
264 /**
265 * Set the page widget of the dialog.
266 *
267 * @note the previous pageWidget will be deleted.
268 *
269 * @param widget The KPageWidget object will be reparented to this object, so you can create
270 * it without parent and you are not allowed to delete it.
271 */
272 void setPageWidget(KPageWidget *widget);
273
274 /**
275 * Returns the button box of the dialog or a null pointer if no button box is set.
276 */
277 QDialogButtonBox *buttonBox();
278
279 /**
280 * Returns the button box of the dialog or a null pointer if no button box is set.
281 */
282 const QDialogButtonBox *buttonBox() const;
283
284 /**
285 * Set the button box of the dialog
286 *
287 * @note the previous buttonBox will be deleted.
288 *
289 * @param box The QDialogButtonBox object will be reparented to this object, so you can create
290 * it without parent and you are not allowed to delete it.
291 */
292 void setButtonBox(QDialogButtonBox *box);
293
294protected:
295 std::unique_ptr<class KPageDialogPrivate> const d_ptr;
296};
297
298#endif
299

source code of kwidgetsaddons/src/kpagedialog.h