File indexing completed on 2025-02-16 13:11:46
0001 /* 0002 This file is part of the KDE Libraries 0003 SPDX-FileCopyrightText: 2006 Tobias Koenig <tokoe@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KPAGEVIEW_H 0009 #define KPAGEVIEW_H 0010 0011 #include <kwidgetsaddons_export.h> 0012 0013 #include <QWidget> 0014 #include <memory> 0015 0016 class KPageModel; 0017 0018 class QAbstractItemDelegate; 0019 class QAbstractItemView; 0020 class QModelIndex; 0021 class KPageViewPrivate; 0022 class QAbstractItemModel; 0023 0024 /** 0025 * @class KPageView kpageview.h KPageView 0026 * 0027 * @short A base class which can handle multiple pages. 0028 * 0029 * This class provides a widget base class which handles multiple 0030 * pages and allows the user to switch between these pages in 0031 * different ways. 0032 * 0033 * Currently, @p Auto, @p Plain, @p List, @p Tree and @p Tabbed face 0034 * types are available (cmp. KPageWidget). 0035 * 0036 * <b>Example:</b>\n 0037 * 0038 * \code 0039 * KPageModel *model = new MyPageModel(); 0040 * 0041 * KPageView *view = new KPageView( this ); 0042 * view->setModel( model ); 0043 * 0044 * view->setFaceType( KPageView::List ); 0045 * \endcode 0046 * 0047 * @author Tobias Koenig (tokoe@kde.org) 0048 */ 0049 class KWIDGETSADDONS_EXPORT KPageView : public QWidget 0050 { 0051 Q_OBJECT 0052 Q_PROPERTY(FaceType faceType READ faceType WRITE setFaceType) 0053 Q_DECLARE_PRIVATE(KPageView) 0054 0055 public: 0056 /** 0057 * This enum is used to decide which type of navigation view 0058 * shall be used in the page view. 0059 */ 0060 enum FaceType { 0061 /** 0062 * Depending on the number of pages in the model, 0063 * the @c Plain (one page), the @c List (several pages) 0064 * or the @c Tree face (nested pages) will be used. 0065 * This is the default face type. 0066 */ 0067 Auto, 0068 /** 0069 * No navigation view will be visible and only the 0070 * first page of the model will be shown. 0071 */ 0072 Plain, 0073 /** 0074 * An icon list is used as navigation view 0075 */ 0076 List, 0077 /** 0078 * A tree list is used as navigation view 0079 */ 0080 Tree, 0081 /** 0082 * A tab widget is used as navigation view 0083 */ 0084 Tabbed, 0085 /** 0086 * A flat list with small icons is used as navigation view 0087 */ 0088 FlatList, 0089 }; 0090 Q_ENUM(FaceType) 0091 0092 /** 0093 * Creates a page view with given parent. 0094 */ 0095 explicit KPageView(QWidget *parent = nullptr); 0096 0097 /** 0098 * Destroys the page view. 0099 */ 0100 ~KPageView() override; 0101 0102 /** 0103 * Sets the @p model of the page view. 0104 * 0105 * The model has to provide data for the roles defined in KPageModel::Role. 0106 */ 0107 void setModel(QAbstractItemModel *model); 0108 0109 /** 0110 * Returns the model of the page view. 0111 */ 0112 QAbstractItemModel *model() const; 0113 0114 /** 0115 * Sets the face type of the page view. 0116 */ 0117 void setFaceType(FaceType faceType); 0118 0119 /** 0120 * Returns the face type of the page view. 0121 */ 0122 FaceType faceType() const; 0123 0124 /** 0125 * Sets the page with @param index to be the current page and emits 0126 * the signal currentPageChanged. 0127 */ 0128 void setCurrentPage(const QModelIndex &index); 0129 0130 /** 0131 * Returns the index for the current page or an invalid index 0132 * if no current page exists. 0133 */ 0134 QModelIndex currentPage() const; 0135 0136 /** 0137 * Sets the item @param delegate which can be used customize 0138 * the page view. 0139 */ 0140 void setItemDelegate(QAbstractItemDelegate *delegate); 0141 0142 /** 0143 * Returns the item delegate of the page view. 0144 */ 0145 QAbstractItemDelegate *itemDelegate() const; 0146 0147 /** 0148 * Sets the @p widget which will be shown when a page is selected 0149 * that has no own widget set. 0150 */ 0151 void setDefaultWidget(QWidget *widget); 0152 0153 /** 0154 * Set a widget as the header for this Page view 0155 * It will replace the standard page title 0156 * @since 5.61 0157 */ 0158 void setPageHeader(QWidget *header); 0159 0160 /** 0161 * Widget of the header for this page view 0162 * @since 5.61 0163 */ 0164 QWidget *pageHeader() const; 0165 0166 /** 0167 * Set a widget as the footer for this Page view 0168 * @since 5.61 0169 */ 0170 void setPageFooter(QWidget *footer); 0171 0172 /** 0173 * Widget of the footer for this page view 0174 * @since 5.61 0175 */ 0176 QWidget *pageFooter() const; 0177 0178 Q_SIGNALS: 0179 /** 0180 * This signal is emitted whenever the current page changes. 0181 * The previous page index is replaced by the current index. 0182 */ 0183 void currentPageChanged(const QModelIndex ¤t, const QModelIndex &previous); 0184 0185 protected: 0186 /** 0187 * Returns the navigation view, depending on the current 0188 * face type. 0189 * 0190 * This method can be reimplemented to provide custom 0191 * navigation views. 0192 */ 0193 virtual QAbstractItemView *createView(); 0194 0195 /** 0196 * Returns whether the page header should be visible. 0197 * 0198 * This method can be reimplemented for adapting custom 0199 * views. 0200 */ 0201 virtual bool showPageHeader() const; 0202 0203 /** 0204 * Returns the position where the navigation view should be 0205 * located according to the page stack. 0206 * 0207 * This method can be reimplemented for adapting custom 0208 * views. 0209 */ 0210 virtual Qt::Alignment viewPosition() const; 0211 0212 KWIDGETSADDONS_NO_EXPORT KPageView(KPageViewPrivate &dd, QWidget *parent); 0213 0214 protected: 0215 std::unique_ptr<class KPageViewPrivate> const d_ptr; 0216 }; 0217 0218 #endif