1/*
2 * This file is part of the KDE Libraries
3 * Copyright (C) 1999-2001 Mirko Boehm (mirko@kde.org) and
4 * Espen Sand (espen@kde.org)
5 * Holger Freyther <freyther@kde.org>
6 * 2005-2006 Olivier Goffart <ogoffart at kde.org>
7 * 2006 Tobias Koenig <tokoe@kde.org>
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
18 *
19 * You should have received a copy of the GNU Library General Public License
20 * along with this library; see the file COPYING.LIB. If not, write to
21 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 * Boston, MA 02110-1301, USA.
23 *
24 */
25#ifndef KPAGEDIALOG_H
26#define KPAGEDIALOG_H
27
28#include <kdialog.h>
29#include <kpagewidget.h>
30
31class KPageDialogPrivate;
32
33/**
34 * @short A dialog base class which can handle multiple pages.
35 *
36 * This class provides a dialog base class which handles multiple
37 * pages and allows the user to switch between these pages in
38 * different ways.
39 *
40 * Currently, @p Auto, @p Plain, @p List, @p Tree and @p Tabbed face
41 * types are available (@see KPageView).
42 *
43 * <b>Example:</b>\n
44 *
45 * \code
46 * UrlDialog::UrlDialog( QWidget *parent )
47 * : KPageDialog( parent )
48 * {
49 * setFaceType( List );
50 *
51 * QLabel *label = new QLabel( "Test Page" );
52 * addPage( label, i18n( "My Test Page" ) );
53 *
54 * label = new QLabel( "Second Test Page" );
55 * KPageWidgetItem *page = new KPageWidgetItem( label, i18n( "My Second Test Page" ) );
56 * page->setHeader( i18n( "My header string" ) );
57 * page->setIcon( KIcon( "file" ) );
58 *
59 * addPage( page );
60 * }
61 * \endcode
62 *
63 * @author Tobias Koenig (tokoe@kde.org)
64 */
65class KDEUI_EXPORT KPageDialog : public KDialog
66{
67 Q_OBJECT
68 Q_DECLARE_PRIVATE(KPageDialog)
69
70 public:
71
72 /**
73 * @li @p Auto - A dialog with a face based on the structure of the
74 * available pages.
75 * If only a single page is added, the dialog behaves like
76 * in @p Plain mode, with multiple pages without sub pages
77 * it behaves like in @p List mode and like in @p Tree mode
78 * otherwise.
79 * @li @p Plain - A normal dialog.
80 * @li @p List - A dialog with an icon list on the left side and a
81 * representation of the contents on the right side.
82 * @li @p Tree - A dialog with a tree on the left side and a
83 * representation of the contents on the right side.
84 * @li @p Tabbed - A dialog with a tab bar above the representation
85 * of the contents.
86 */
87 enum FaceType
88 {
89 Auto = KPageView::Auto,
90 Plain = KPageView::Plain,
91 List = KPageView::List,
92 Tree = KPageView::Tree,
93 Tabbed = KPageView::Tabbed
94 };
95
96 public:
97 /**
98 * Creates a new page dialog.
99 */
100 explicit KPageDialog( QWidget *parent = 0, Qt::WindowFlags flags = 0 );
101
102 /**
103 * Destroys the page dialog.
104 */
105 ~KPageDialog();
106
107 /**
108 * Sets the face type of the dialog.
109 */
110 void setFaceType( FaceType faceType );
111
112 /**
113 * Adds a new top level page to the dialog.
114 *
115 * @param widget The widget of the page.
116 * @param name The name which is displayed in the navigation view.
117 *
118 * @returns The associated @see KPageWidgetItem.
119 */
120 KPageWidgetItem* addPage( QWidget *widget, const QString &name );
121
122 /**
123 * Adds a new top level page to the dialog.
124 *
125 * @param item The @see KPageWidgetItem which describes the page.
126 */
127 void addPage( KPageWidgetItem *item );
128
129 /**
130 * Inserts a new page in the dialog.
131 *
132 * @param before The new page will be insert before this @see KPageWidgetItem
133 * on the same level in hierarchy.
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 @see KPageWidgetItem.
138 */
139 KPageWidgetItem* insertPage( KPageWidgetItem *before, QWidget *widget, const QString &name );
140
141 /**
142 * Inserts a new page in the dialog.
143 *
144 * @param before The new page will be insert before this @see KPageWidgetItem
145 * on the same level in hierarchy.
146 *
147 * @param item The @see KPageWidgetItem which describes the page.
148 */
149 void insertPage( KPageWidgetItem *before, KPageWidgetItem *item );
150
151 /**
152 * Inserts a new sub page in the dialog.
153 *
154 * @param parent The new page will be insert as child of this @see KPageWidgetItem.
155 * @param widget The widget of the page.
156 * @param name The name which is displayed in the navigation view.
157 *
158 * @returns The associated @see KPageWidgetItem.
159 */
160 KPageWidgetItem* addSubPage( KPageWidgetItem *parent, QWidget *widget, const QString &name );
161
162 /**
163 * Inserts a new sub page in the dialog.
164 *
165 * @param parent The new page will be insert as child of this @see KPageWidgetItem.
166 *
167 * @param item The @see KPageWidgetItem which describes the page.
168 */
169 void addSubPage( KPageWidgetItem *parent, KPageWidgetItem *item );
170
171 /**
172 * Removes the page associated with the given @see KPageWidgetItem.
173 */
174 void removePage( KPageWidgetItem *item );
175
176 /**
177 * Sets the page which is associated with the given @see KPageWidgetItem to
178 * be the current page and emits the currentPageChanged() signal.
179 */
180 void setCurrentPage( KPageWidgetItem *item );
181
182 /**
183 * Returns the @see KPageWidgetItem for the current page or 0 if there is no
184 * current page.
185 */
186 KPageWidgetItem* currentPage() const;
187
188 Q_SIGNALS:
189 /**
190 * This signal is emitted whenever the current page has changed.
191 *
192 * @param item The new current page or 0 if no current page is available.
193 */
194 void currentPageChanged( KPageWidgetItem *current, KPageWidgetItem *before );
195
196 /**
197 * This signal is emitted whenever a page has been removed.
198 *
199 * @param page The page which has been removed
200 **/
201 void pageRemoved( KPageWidgetItem *page );
202
203 protected:
204 /**
205 * This constructor can be used by subclasses to provide a custom page widget.
206 *
207 * \param widget The KPageWidget object will be reparented to this object, so you can create
208 * it without parent and you are not allowed to delete it.
209 */
210 KPageDialog(KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = 0);
211 KPageDialog(KPageDialogPrivate &dd, KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags = 0);
212
213 /**
214 * Returns the page widget of the dialog or 0 if no page widget is set.
215 */
216 KPageWidget *pageWidget();
217
218 /**
219 * Returns the page widget of the dialog or 0 if no page widget is set.
220 */
221 const KPageWidget *pageWidget() const;
222
223 /**
224 * Set the page widget of the dialog.
225 *
226 * @note the previous pageWidget will be deleted.
227 *
228 * @param widget The KPageWidget object will be reparented to this object, so you can create
229 * it without parent and you are not allowed to delete it.
230 */
231 void setPageWidget(KPageWidget *widget);
232
233};
234
235#endif
236