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

source code of kwidgetsaddons/src/kpagedialog.h