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 KPAGEVIEW_H
23#define KPAGEVIEW_H
24
25#include <kdeui_export.h>
26
27#include <QtGui/QWidget>
28
29class KPageModel;
30
31class QAbstractItemDelegate;
32class QAbstractItemView;
33class QModelIndex;
34class KPageViewPrivate;
35class QAbstractItemModel;
36
37/**
38 * @short A base class which can handle multiple pages.
39 *
40 * This class provides a widget base class which handles multiple
41 * pages and allows the user to switch between these pages in
42 * different ways.
43 *
44 * Currently, @p Auto, @p Plain, @p List, @p Tree and @p Tabbed face
45 * types are available. @see KPageWidget
46 *
47 * <b>Example:</b>\n
48 *
49 * \code
50 * KPageModel *model = new MyPageModel();
51 *
52 * KPageView *view = new KPageView( this );
53 * view->setModel( model );
54 *
55 * view->setFaceType( KPageView::List );
56 * \endcode
57 *
58 * @author Tobias Koenig (tokoe@kde.org)
59 */
60class KDEUI_EXPORT KPageView : public QWidget
61{
62 Q_OBJECT
63 Q_ENUMS( FaceType )
64 Q_PROPERTY( FaceType faceType READ faceType WRITE setFaceType )
65 Q_DECLARE_PRIVATE(KPageView)
66
67 public:
68 /**
69 * This enum is used to decide which type of navigation view
70 * shall be used in the page view.
71 *
72 * @li Auto - Depending on the number of pages in the model,
73 * the Plain (one page), the List (several pages)
74 * or the Tree face (nested pages) will be used.
75 * This is the default face type.
76 * @li Plain - No navigation view will be visible and only the
77 * first page of the model will be shown.
78 *
79 * @li List - An icon list is used as navigation view.
80 *
81 * @li Tree - A tree list is used as navigation view.
82 *
83 * @li Tabbed - A tab widget is used as navigation view.
84 */
85 enum FaceType
86 {
87 Auto,
88 Plain,
89 List,
90 Tree,
91 Tabbed
92 };
93
94 /**
95 * Creates a page view with given parent.
96 */
97 explicit KPageView( QWidget *parent = 0 );
98
99 /**
100 * Destroys the page view.
101 */
102 virtual ~KPageView();
103
104 /**
105 * Sets the @p model of the page view.
106 *
107 * The model has to provide data for the roles defined in KPageModel::Role.
108 */
109 void setModel(QAbstractItemModel *model);
110
111 /**
112 * Returns the model of the page view.
113 */
114 QAbstractItemModel* model() const;
115
116 /**
117 * Sets the face type of the page view.
118 */
119 void setFaceType( FaceType faceType );
120
121 /**
122 * Returns the face type of the page view.
123 */
124 FaceType faceType() const;
125
126 /**
127 * Sets the page with @param index to be the current page and emits
128 * the @see currentPageChanged signal.
129 */
130 void setCurrentPage( const QModelIndex &index );
131
132 /**
133 * Returns the index for the current page or an invalid index
134 * if no current page exists.
135 */
136 QModelIndex currentPage() const;
137
138 /**
139 * Sets the item @param delegate which can be used customize
140 * the page view.
141 */
142 void setItemDelegate( QAbstractItemDelegate *delegate );
143
144 /**
145 * Returns the item delegate of the page view.
146 */
147 QAbstractItemDelegate* itemDelegate() const;
148
149 /**
150 * Sets the @p widget which will be shown when a page is selected
151 * that has no own widget set.
152 */
153 void setDefaultWidget( QWidget *widget );
154
155 Q_SIGNALS:
156 /**
157 * This signal is emitted whenever the current page changes.
158 * The previous page index is replaced by the current index.
159 */
160 void currentPageChanged( const QModelIndex &current, const QModelIndex &previous );
161
162 protected:
163 /**
164 * Returns the navigation view, depending on the current
165 * face type.
166 *
167 * This method can be reimplemented to provide custom
168 * navigation views.
169 */
170 virtual QAbstractItemView* createView();
171
172 /**
173 * Returns whether the page header should be visible.
174 *
175 * This method can be reimplemented for adapting custom
176 * views.
177 */
178 virtual bool showPageHeader() const;
179
180 /**
181 * Returns the position where the navigation view should be
182 * located according to the page stack.
183 *
184 * This method can be reimplemented for adapting custom
185 * views.
186 */
187 virtual Qt::Alignment viewPosition() const;
188
189 KPageView(KPageViewPrivate &dd, QWidget *parent);
190 KPageViewPrivate *const d_ptr;
191
192 private:
193 Q_PRIVATE_SLOT(d_func(), void _k_rebuildGui())
194 Q_PRIVATE_SLOT(d_func(), void _k_modelChanged())
195 Q_PRIVATE_SLOT(d_func(), void _k_pageSelected(const QItemSelection &, const QItemSelection &))
196 Q_PRIVATE_SLOT(d_func(), void _k_dataChanged(const QModelIndex &, const QModelIndex &))
197};
198
199#endif
200