1/*
2 This file is part of the KDE Libraries
3
4 Copyright (C) 2006 Tobias Koenig (tokoe@kde.org)
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KPAGEWIDGETMODEL_H
23#define KPAGEWIDGETMODEL_H
24
25#include "kpagemodel.h"
26
27class QWidget;
28
29class KIcon;
30
31/**
32 * KPageWidgetItem is used by @ref KPageWidget and represents
33 * a page.
34 *
35 * <b>Example:</b>\n
36 *
37 * \code
38 * ColorPage *page = new ColorPage;
39 *
40 * KPageWidgetItem *item = new KPageWidgetItem( page, i18n( "Colors" ) );
41 * item->setHeader( i18n( "Colors of Main Window" ) );
42 * item->setIcon( KIcon( "colors" ) );
43 *
44 * KPageWidget *pageWidget = new KPageWidget( this );
45 * pageWidget->addPage( item );
46 * \endcode
47 *
48 * @author Tobias Koenig (tokoe@kde.org)
49 */
50class KDEUI_EXPORT KPageWidgetItem : public QObject
51{
52 Q_OBJECT
53 Q_PROPERTY( QString name READ name WRITE setName )
54 Q_PROPERTY( QString header READ header WRITE setHeader )
55 Q_PROPERTY( KIcon icon READ icon WRITE setIcon )
56 Q_PROPERTY( bool checkable READ isCheckable WRITE setCheckable )
57 Q_PROPERTY( bool checked READ isChecked WRITE setChecked )
58 /**
59 * This property holds whether the item is enabled.
60 *
61 * It dis-/enables both the widget and the item in the list-/treeview.
62 */
63 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled)
64
65 public:
66 /**
67 * Creates a new page widget item.
68 *
69 * @param widget The widget that is shown as page in the KPageWidget.
70 */
71 KPageWidgetItem( QWidget *widget );
72
73 /**
74 * Creates a new page widget item.
75 *
76 * @param widget The widget that is shown as page in the KPageWidget.
77 * @param name The localized string that is show in the navigation view
78 * of the KPageWidget.
79 */
80 KPageWidgetItem( QWidget *widget, const QString &name );
81
82 /**
83 * Destroys the page widget item.
84 */
85 ~KPageWidgetItem();
86
87 /**
88 * Returns the widget of the page widget item.
89 */
90 QWidget* widget() const;
91
92 /**
93 * Sets the name of the item as shown in the navigation view of the page
94 * widget.
95 */
96 void setName( const QString &name );
97
98 /**
99 * Returns the name of the page widget item.
100 */
101 QString name() const;
102
103 /**
104 * Sets the header of the page widget item.
105 *
106 * If setHeader(QString()) is used, what is the default if the header
107 * does not got set explicit, then the defined name() will also be used
108 * for the header. If setHeader("") is used, the header will be hidden
109 * even if the @a KPageView::FaceType is something else then Tabbed.
110 *
111 * @param header Header of the page widget item.
112 */
113 void setHeader( const QString &header );
114
115 /**
116 * Returns the header of the page widget item.
117 */
118 QString header() const;
119
120 /**
121 * Sets the icon of the page widget item.
122 * @param icon Icon of the page widget item.
123 */
124 void setIcon( const KIcon &icon );
125
126 /**
127 * Returns the icon of the page widget item.
128 */
129 KIcon icon() const;
130
131 /**
132 * Sets whether the page widget item is checkable in the view.
133 * @param checkable True if the page widget is checkable,
134 * otherwise false.
135 */
136 void setCheckable( bool checkable );
137
138 /**
139 * Returns whether the page widget item is checkable.
140 */
141 bool isCheckable() const;
142
143 /**
144 * Returns whether the page widget item is checked.
145 */
146 bool isChecked() const;
147
148 /**
149 * Returns whether the page widget item is enabled.
150 */
151 bool isEnabled() const;
152
153 public Q_SLOTS:
154 /**
155 * Sets whether the page widget item is enabled.
156 */
157 void setEnabled(bool);
158
159 /**
160 * Sets whether the page widget item is checked.
161 */
162 void setChecked( bool checked );
163
164 Q_SIGNALS:
165 /**
166 * This signal is emitted whenever the icon or header
167 * is changed.
168 */
169 void changed();
170
171 /**
172 * This signal is emitted whenever the user checks or
173 * unchecks the item of @see setChecked() is called.
174 */
175 void toggled( bool checked );
176
177 private:
178 class Private;
179 Private* const d;
180};
181
182class KPageWidgetModelPrivate;
183
184/**
185 * This page model is used by @see KPageWidget to provide
186 * a hierarchical layout of pages.
187 */
188class KDEUI_EXPORT KPageWidgetModel : public KPageModel
189{
190 Q_OBJECT
191 Q_DECLARE_PRIVATE(KPageWidgetModel)
192
193 public:
194 /**
195 * Creates a new page widget model.
196 *
197 * @param parent The parent object.
198 */
199 explicit KPageWidgetModel( QObject *parent = 0 );
200
201 /**
202 * Destroys the page widget model.
203 */
204 ~KPageWidgetModel();
205
206 /**
207 * Adds a new top level page to the model.
208 *
209 * @param widget The widget of the page.
210 * @param name The name which is displayed in the navigation view.
211 *
212 * @returns The associated @see KPageWidgetItem.
213 */
214 KPageWidgetItem* addPage( QWidget *widget, const QString &name );
215
216 /**
217 * Adds a new top level page to the model.
218 *
219 * @param item The @see KPageWidgetItem which describes the page.
220 */
221 void addPage( KPageWidgetItem *item );
222
223 /**
224 * Inserts a new page in the model.
225 *
226 * @param before The new page will be insert before this @see KPageWidgetItem
227 * on the same level in hierarchy.
228 * @param widget The widget of the page.
229 * @param name The name which is displayed in the navigation view.
230 *
231 * @returns The associated @see KPageWidgetItem.
232 */
233 KPageWidgetItem* insertPage( KPageWidgetItem *before, QWidget *widget, const QString &name );
234
235 /**
236 * Inserts a new page in the model.
237 *
238 * @param before The new page will be insert before this @see KPageWidgetItem
239 * on the same level in hierarchy.
240 *
241 * @param item The @see KPageWidgetItem which describes the page.
242 */
243 void insertPage( KPageWidgetItem *before, KPageWidgetItem *item );
244
245 /**
246 * Inserts a new sub page in the model.
247 *
248 * @param parent The new page will be insert as child of this @see KPageWidgetItem.
249 * @param widget The widget of the page.
250 * @param name The name which is displayed in the navigation view.
251 *
252 * @returns The associated @see KPageWidgetItem.
253 */
254 KPageWidgetItem* addSubPage( KPageWidgetItem *parent, QWidget *widget, const QString &name );
255
256 /**
257 * Inserts a new sub page in the model.
258 *
259 * @param parent The new page will be insert as child of this @see KPageWidgetItem.
260 *
261 * @param item The @see KPageWidgetItem which describes the page.
262 */
263 void addSubPage( KPageWidgetItem *parent, KPageWidgetItem *item );
264
265 /**
266 * Removes the page associated with the given @see KPageWidgetItem.
267 */
268 void removePage( KPageWidgetItem *item );
269
270 /**
271 * These methods are reimplemented from QAbstractItemModel.
272 */
273 virtual int columnCount( const QModelIndex &parent = QModelIndex() ) const;
274 virtual QVariant data( const QModelIndex &index, int role = Qt::DisplayRole ) const;
275 virtual bool setData( const QModelIndex &index, const QVariant &value, int role = Qt::EditRole );
276 virtual Qt::ItemFlags flags( const QModelIndex &index ) const;
277 virtual QModelIndex index( int row, int column, const QModelIndex &parent = QModelIndex() ) const;
278 virtual QModelIndex parent( const QModelIndex &index ) const;
279 virtual int rowCount( const QModelIndex &parent = QModelIndex() ) const;
280
281 /**
282 * Returns the @see KPageWidgetItem for a given index or 0 if the index is invalid.
283 */
284 KPageWidgetItem *item(const QModelIndex &index) const;
285
286 /**
287 * Returns the index for a given @see KPageWidgetItem. The index is invalid if the
288 * item can't be found in the model.
289 */
290 QModelIndex index( const KPageWidgetItem *item ) const;
291
292 Q_SIGNALS:
293 /**
294 * This signal is emitted whenever a checkable page changes its state. @param checked is true
295 * when the @param page is checked, or false if the @param page is unchecked.
296 */
297 void toggled( KPageWidgetItem *page, bool checked );
298
299 private:
300 Q_PRIVATE_SLOT(d_func(), void _k_itemChanged())
301 Q_PRIVATE_SLOT(d_func(), void _k_itemToggled(bool))
302};
303
304#endif
305