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 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 (tokoe@kde.org) 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 */ 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 115 public: 116 /** 117 * Creates a new page dialog. 118 */ 119 explicit KPageDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags()); 120 121 /** 122 * Destroys the page dialog. 123 */ 124 ~KPageDialog() override; 125 126 /** 127 * Sets the face type of the dialog. 128 */ 129 void setFaceType(FaceType faceType); 130 131 /** 132 * Adds a new top level page to the dialog. 133 * 134 * @param widget The widget of the page. 135 * @param name The name which is displayed in the navigation view. 136 * 137 * @returns The associated KPageWidgetItem. 138 */ 139 KPageWidgetItem *addPage(QWidget *widget, const QString &name); 140 141 /** 142 * Adds a new top level page to the dialog. 143 * 144 * @param item The KPageWidgetItem which describes the page. 145 */ 146 void addPage(KPageWidgetItem *item); 147 148 /** 149 * Inserts a new page in the dialog. 150 * 151 * @param before The new page will be insert before this KPageWidgetItem 152 * on the same level in hierarchy. 153 * @param widget The widget of the page. 154 * @param name The name which is displayed in the navigation view. 155 * 156 * @returns The associated KPageWidgetItem. 157 */ 158 KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name); 159 160 /** 161 * Inserts a new page in the dialog. 162 * 163 * @param before The new page will be insert before this KPageWidgetItem 164 * on the same level in hierarchy. 165 * 166 * @param item The KPageWidgetItem which describes the page. 167 */ 168 void insertPage(KPageWidgetItem *before, KPageWidgetItem *item); 169 170 /** 171 * Inserts a new sub page in the dialog. 172 * 173 * @param parent The new page will be insert as child of this KPageWidgetItem. 174 * @param widget The widget of the page. 175 * @param name The name which is displayed in the navigation view. 176 * 177 * @returns The associated KPageWidgetItem. 178 */ 179 KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name); 180 181 /** 182 * Inserts a new sub page in the dialog. 183 * 184 * @param parent The new page will be insert as child of this KPageWidgetItem. 185 * 186 * @param item The KPageWidgetItem which describes the page. 187 */ 188 void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item); 189 190 /** 191 * Removes the page associated with the given KPageWidgetItem. 192 */ 193 void removePage(KPageWidgetItem *item); 194 195 /** 196 * Sets the page which is associated with the given KPageWidgetItem to 197 * be the current page and emits the currentPageChanged() signal. 198 */ 199 void setCurrentPage(KPageWidgetItem *item); 200 201 /** 202 * Returns the KPageWidgetItem for the current page or a null pointer if there is no 203 * current page. 204 */ 205 KPageWidgetItem *currentPage() const; 206 207 /** 208 * Sets the collection of standard buttons displayed by this dialog. 209 */ 210 void setStandardButtons(QDialogButtonBox::StandardButtons buttons); 211 212 /** 213 * Returns the QPushButton corresponding to the standard button which, or a null pointer if the standard 214 * button doesn't exist in this dialog. 215 */ 216 QPushButton *button(QDialogButtonBox::StandardButton which) const; 217 218 /** 219 * Set an action button. 220 */ 221 void addActionButton(QAbstractButton *button); 222 223 Q_SIGNALS: 224 /** 225 * This signal is emitted whenever the current page has changed. 226 * 227 * @param current The new current page or a null pointer if no current page is available. 228 * @param before The page that was current before the new current page has changed. 229 */ 230 void currentPageChanged(KPageWidgetItem *current, KPageWidgetItem *before); 231 232 /** 233 * This signal is emitted whenever a page has been removed. 234 * 235 * @param page The page which has been removed 236 */ 237 void pageRemoved(KPageWidgetItem *page); 238 239 protected: 240 /** 241 * This constructor can be used by subclasses to provide a custom page widget. 242 * 243 * \param widget The KPageWidget object will be reparented to this object, so you can create 244 * it without parent and you are not allowed to delete it. 245 */ 246 KPageDialog(KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags()); 247 KPageDialog(KPageDialogPrivate &dd, KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags()); 248 249 /** 250 * Returns the page widget of the dialog or a null pointer if no page widget is set. 251 */ 252 KPageWidget *pageWidget(); 253 254 /** 255 * Returns the page widget of the dialog or a null pointer if no page widget is set. 256 */ 257 const KPageWidget *pageWidget() const; 258 259 /** 260 * Set the page widget of the dialog. 261 * 262 * @note the previous pageWidget will be deleted. 263 * 264 * @param widget The KPageWidget object will be reparented to this object, so you can create 265 * it without parent and you are not allowed to delete it. 266 */ 267 void setPageWidget(KPageWidget *widget); 268 269 /** 270 * Returns the button box of the dialog or a null pointer if no button box is set. 271 */ 272 QDialogButtonBox *buttonBox(); 273 274 /** 275 * Returns the button box of the dialog or a null pointer if no button box is set. 276 */ 277 const QDialogButtonBox *buttonBox() const; 278 279 /** 280 * Set the button box of the dialog 281 * 282 * @note the previous buttonBox will be deleted. 283 * 284 * @param box The QDialogButtonBox object will be reparented to this object, so you can create 285 * it without parent and you are not allowed to delete it. 286 */ 287 void setButtonBox(QDialogButtonBox *box); 288 289 protected: 290 std::unique_ptr<class KPageDialogPrivate> const d_ptr; 291 }; 292 293 #endif 294