1/*
2 This file is part of the KDE Libraries
3 SPDX-FileCopyrightText: 2006 Tobias Koenig <tokoe@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPAGEVIEW_H
9#define KPAGEVIEW_H
10
11#include <kwidgetsaddons_export.h>
12
13#include <QWidget>
14#include <memory>
15
16class KPageModel;
17
18class QAbstractItemDelegate;
19class QAbstractItemView;
20class QModelIndex;
21class KPageViewPrivate;
22class QAbstractItemModel;
23
24/*!
25 * \class KPageView
26 * \inmodule KWidgetsAddons
27 *
28 * \brief A base class which can handle multiple pages.
29 *
30 * This class provides a widget base class which handles multiple
31 * pages and allows the user to switch between these pages in
32 * different ways.
33 *
34 * Currently, Auto, Plain, List, Tree, FlatList and
35 * Tabbed face types are available (cmp. KPageWidget).
36 *
37 * Example:
38 *
39 * \code
40 * KPageModel *model = new MyPageModel();
41 *
42 * auto view = new KPageView(this);
43 * view->setModel(model);
44 *
45 * view->setFaceType(KPageView::List);
46 * \endcode
47 */
48class KWIDGETSADDONS_EXPORT KPageView : public QWidget
49{
50 Q_OBJECT
51
52 /*!
53 * \property KPageView::pageHeader
54 */
55 Q_PROPERTY(QWidget *pageHeader READ pageHeader WRITE setPageHeader)
56
57 /*!
58 * \property KPageView::pageFooter
59 */
60 Q_PROPERTY(QWidget *pageFooter READ pageFooter WRITE setPageFooter)
61
62 /*!
63 * \property KPageView::faceType
64 */
65 Q_PROPERTY(FaceType faceType READ faceType WRITE setFaceType)
66 Q_DECLARE_PRIVATE(KPageView)
67
68public:
69 /*!
70 * This enum is used to decide which type of navigation view
71 * shall be used in the page view.
72 *
73 * \value Auto Depending on the number of pages in the model, the Plain (one page), the List (several pages) the Tree face (nested pages) will be used. This
74 * is the default face type.
75 * \value Plain No navigation view will be visible and only the first page of the model will be shown.
76 * \value List An icon list is used as navigation view
77 * \value Tree A tree list is used as navigation view
78 * \value Tabbed A tab widget is used as navigation view
79 * \value FlatList A flat list with small icons is used as navigation view
80 */
81 enum FaceType {
82 Auto,
83 Plain,
84 List,
85 Tree,
86 Tabbed,
87 FlatList,
88 };
89 Q_ENUM(FaceType)
90
91 /*!
92 * Creates a page view with given parent.
93 */
94 explicit KPageView(QWidget *parent = nullptr);
95
96 ~KPageView() override;
97
98 /*!
99 * Sets the \a model of the page view.
100 *
101 * The model has to provide data for the roles defined in KPageModel::Role.
102 */
103 void setModel(QAbstractItemModel *model);
104
105 /*!
106 * Returns the model of the page view.
107 */
108 QAbstractItemModel *model() const;
109
110 /*!
111 * Sets the face type of the page view.
112 */
113 void setFaceType(FaceType faceType);
114
115 /*!
116 * Returns the face type of the page view.
117 */
118 FaceType faceType() const;
119
120 /*!
121 * Sets the page with \a index to be the current page and emits
122 * the signal currentPageChanged.
123 */
124 void setCurrentPage(const QModelIndex &index);
125
126 /*!
127 * Returns the index for the current page or an invalid index
128 * if no current page exists.
129 */
130 QModelIndex currentPage() const;
131
132 /*!
133 * Sets the item \a delegate which can be used customize
134 * the page view.
135 */
136 void setItemDelegate(QAbstractItemDelegate *delegate);
137
138 /*!
139 * Returns the item delegate of the page view.
140 */
141 QAbstractItemDelegate *itemDelegate() const;
142
143 /*!
144 * Sets the \a widget which will be shown when a page is selected
145 * that has no own widget set.
146 */
147 void setDefaultWidget(QWidget *widget);
148
149 /*!
150 * Set a widget as the header for this Page view
151 * It will replace the standard page title
152 * \since 5.61
153 */
154 void setPageHeader(QWidget *header);
155
156 /*!
157 * Widget of the header for this page view
158 * \since 5.61
159 */
160 QWidget *pageHeader() const;
161
162 /*!
163 * Set a widget as the footer for this Page view
164 * \since 5.61
165 */
166 void setPageFooter(QWidget *footer);
167
168 /*!
169 * Widget of the footer for this page view
170 * \since 5.61
171 */
172 QWidget *pageFooter() const;
173
174Q_SIGNALS:
175 /*!
176 * This signal is emitted whenever the current page changes.
177 * The previous page index is replaced by the current index.
178 */
179 void currentPageChanged(const QModelIndex &current, const QModelIndex &previous);
180
181protected:
182 /*!
183 * Returns the navigation view, depending on the current
184 * face type.
185 *
186 * This method can be reimplemented to provide custom
187 * navigation views.
188 */
189 virtual QAbstractItemView *createView();
190
191 /*!
192 * Returns whether the page header should be visible.
193 *
194 * This method can be reimplemented for adapting custom
195 * views.
196 */
197 virtual bool showPageHeader() const;
198
199 /*!
200 * Returns the position where the navigation view should be
201 * located according to the page stack.
202 *
203 * This method can be reimplemented for adapting custom
204 * views.
205 */
206 virtual Qt::Alignment viewPosition() const;
207
208 KWIDGETSADDONS_NO_EXPORT KPageView(KPageViewPrivate &dd, QWidget *parent);
209
210protected:
211 std::unique_ptr<class KPageViewPrivate> const d_ptr;
212};
213
214#endif
215

source code of kwidgetsaddons/src/kpageview.h