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 kpageview.h KPageView
26 *
27 * @short A base class which can handle multiple pages.
28 *
29 * This class provides a widget base class which handles multiple
30 * pages and allows the user to switch between these pages in
31 * different ways.
32 *
33 * Currently, @p Auto, @p Plain, @p List, @p Tree, @p FlatList and
34 * @p Tabbed face types are available (cmp. KPageWidget).
35 *
36 * <b>Example:</b>\n
37 *
38 * \code
39 * KPageModel *model = new MyPageModel();
40 *
41 * auto view = new KPageView(this);
42 * view->setModel(model);
43 *
44 * view->setFaceType(KPageView::List);
45 * \endcode
46 *
47 * @author Tobias Koenig (tokoe@kde.org)
48 */
49class KWIDGETSADDONS_EXPORT KPageView : public QWidget
50{
51 Q_OBJECT
52 Q_PROPERTY(QWidget *pageHeader READ pageHeader WRITE setPageHeader)
53 Q_PROPERTY(QWidget *pageFooter READ pageFooter WRITE setPageFooter)
54 Q_PROPERTY(FaceType faceType READ faceType WRITE setFaceType)
55 Q_DECLARE_PRIVATE(KPageView)
56
57public:
58 /**
59 * This enum is used to decide which type of navigation view
60 * shall be used in the page view.
61 */
62 enum FaceType {
63 /**
64 * Depending on the number of pages in the model,
65 * the @c Plain (one page), the @c List (several pages)
66 * or the @c Tree face (nested pages) will be used.
67 * This is the default face type.
68 */
69 Auto,
70 /**
71 * No navigation view will be visible and only the
72 * first page of the model will be shown.
73 */
74 Plain,
75 /**
76 * An icon list is used as navigation view
77 */
78 List,
79 /**
80 * A tree list is used as navigation view
81 */
82 Tree,
83 /**
84 * A tab widget is used as navigation view
85 */
86 Tabbed,
87 /**
88 * A flat list with small icons is used as navigation view
89 */
90 FlatList,
91 };
92 Q_ENUM(FaceType)
93
94 /**
95 * Creates a page view with given parent.
96 */
97 explicit KPageView(QWidget *parent = nullptr);
98
99 /**
100 * Destroys the page view.
101 */
102 ~KPageView() override;
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 signal currentPageChanged.
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 /**
156 * Set a widget as the header for this Page view
157 * It will replace the standard page title
158 * @since 5.61
159 */
160 void setPageHeader(QWidget *header);
161
162 /**
163 * Widget of the header for this page view
164 * @since 5.61
165 */
166 QWidget *pageHeader() const;
167
168 /**
169 * Set a widget as the footer for this Page view
170 * @since 5.61
171 */
172 void setPageFooter(QWidget *footer);
173
174 /**
175 * Widget of the footer for this page view
176 * @since 5.61
177 */
178 QWidget *pageFooter() const;
179
180Q_SIGNALS:
181 /**
182 * This signal is emitted whenever the current page changes.
183 * The previous page index is replaced by the current index.
184 */
185 void currentPageChanged(const QModelIndex &current, const QModelIndex &previous);
186
187protected:
188 /**
189 * Returns the navigation view, depending on the current
190 * face type.
191 *
192 * This method can be reimplemented to provide custom
193 * navigation views.
194 */
195 virtual QAbstractItemView *createView();
196
197 /**
198 * Returns whether the page header should be visible.
199 *
200 * This method can be reimplemented for adapting custom
201 * views.
202 */
203 virtual bool showPageHeader() const;
204
205 /**
206 * Returns the position where the navigation view should be
207 * located according to the page stack.
208 *
209 * This method can be reimplemented for adapting custom
210 * views.
211 */
212 virtual Qt::Alignment viewPosition() const;
213
214 KWIDGETSADDONS_NO_EXPORT KPageView(KPageViewPrivate &dd, QWidget *parent);
215
216protected:
217 std::unique_ptr<class KPageViewPrivate> const d_ptr;
218};
219
220#endif
221

source code of kwidgetsaddons/src/kpageview.h