KWidgetsAddons

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

KDE's Doxygen guidelines are available online.