KWidgetsAddons

kpagedialog.h
1 /*
2  This file is part of the KDE Libraries
3  SPDX-FileCopyrightText: 1999-2001 Mirko Boehm <[email protected]>
4  SPDX-FileCopyrightText: 1999-2001 Espen Sand <[email protected]>
5  SPDX-FileCopyrightText: 1999-2001 Holger Freyther <[email protected]>
6  SPDX-FileCopyrightText: 2005-2006 Olivier Goffart <ogoffart at kde.org>
7  SPDX-FileCopyrightText: 2006 Tobias Koenig <[email protected]>
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 
19 class 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 ([email protected])
76  */
77 class KWIDGETSADDONS_EXPORT KPageDialog : public QDialog
78 {
79  Q_OBJECT
80  Q_DECLARE_PRIVATE(KPageDialog)
81 
82 public:
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  */
94  /**
95  * A normal dialog
96  */
98  /**
99  * A dialog with an icon list on the left side and a
100  * representation of the contents on the right side
101  */
103  /**
104  * A dialog with a tree on the left side and a
105  * representation of the contents on the right side
106  */
108  /**
109  * A dialog with a tab bar above the representation
110  * of the contents
111  */
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  */
118  };
119 
120 public:
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 
228 Q_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 
244 protected:
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 
294 protected:
295  std::unique_ptr<class KPageDialogPrivate> const d_ptr;
296 };
297 
298 #endif
@ Plain
No navigation view will be visible and only the first page of the model will be shown.
Definition: kpageview.h:72
@ FlatList
A flat list with small icons is used as navigation view.
Definition: kpageview.h:88
@ Tree
A tree list is used as navigation view.
Definition: kpageview.h:80
@ Auto
Depending on the number of pages in the model, the Plain (one page), the List (several pages) or the ...
Definition: kpageview.h:67
typedef WindowFlags
Page widget with many layouts (faces). A KPageView with hierarchical page model.
Definition: kpagewidget.h:24
@ Tabbed
A tab widget is used as navigation view.
Definition: kpageview.h:84
typedef StandardButtons
Q_SIGNALSQ_SIGNALS
A dialog base class which can handle multiple pages.
Definition: kpagedialog.h:77
FaceType
The face types supported.
Definition: kpagedialog.h:86
@ List
An icon list is used as navigation view.
Definition: kpageview.h:76
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Dec 11 2023 04:01:37 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.