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 | |
31 | class 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 | */ |
65 | class 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 ( 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 | |