File indexing completed on 2025-02-16 13:11:47
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 KPAGEWIDGETMODEL_H 0009 #define KPAGEWIDGETMODEL_H 0010 0011 #include "kpagemodel.h" 0012 #include <memory> 0013 0014 class QWidget; 0015 0016 /** 0017 * @class KPageWidgetItem kpagewidgetmodel.h KPageWidgetItem 0018 * 0019 * KPageWidgetItem is used by @ref KPageWidget and represents 0020 * a page. 0021 * 0022 * <b>Example:</b>\n 0023 * 0024 * \code 0025 * ColorPage *page = new ColorPage; 0026 * 0027 * KPageWidgetItem *item = new KPageWidgetItem( page, i18n( "Colors" ) ); 0028 * item->setHeader( i18n( "Colors of Main Window" ) ); 0029 * item->setIcon( QIcon::fromTheme( "colors" ) ); 0030 * 0031 * KPageWidget *pageWidget = new KPageWidget( this ); 0032 * pageWidget->addPage( item ); 0033 * \endcode 0034 * 0035 * @author Tobias Koenig (tokoe@kde.org) 0036 */ 0037 class KWIDGETSADDONS_EXPORT KPageWidgetItem : public QObject 0038 { 0039 Q_OBJECT 0040 Q_PROPERTY(QString name READ name WRITE setName) 0041 Q_PROPERTY(QString header READ header WRITE setHeader) 0042 Q_PROPERTY(QIcon icon READ icon WRITE setIcon) 0043 Q_PROPERTY(bool checkable READ isCheckable WRITE setCheckable) 0044 Q_PROPERTY(bool checked READ isChecked WRITE setChecked) 0045 /** 0046 * This property holds whether the item is enabled. 0047 * 0048 * It dis-/enables both the widget and the item in the list-/treeview. 0049 */ 0050 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled) 0051 /** 0052 * @since 5.52 0053 */ 0054 Q_PROPERTY(bool headerVisible READ isHeaderVisible WRITE setHeaderVisible) 0055 public: 0056 /** 0057 * Creates a new page widget item. 0058 * 0059 * @param widget The widget that is shown as page in the KPageWidget. 0060 */ 0061 KPageWidgetItem(QWidget *widget); 0062 0063 /** 0064 * Creates a new page widget item. 0065 * 0066 * @param widget The widget that is shown as page in the KPageWidget. 0067 * @param name The localized string that is show in the navigation view 0068 * of the KPageWidget. 0069 */ 0070 KPageWidgetItem(QWidget *widget, const QString &name); 0071 0072 /** 0073 * Destroys the page widget item. 0074 */ 0075 ~KPageWidgetItem() override; 0076 0077 /** 0078 * Returns the widget of the page widget item. 0079 */ 0080 QWidget *widget() const; 0081 0082 /** 0083 * Sets the name of the item as shown in the navigation view of the page 0084 * widget. 0085 */ 0086 void setName(const QString &name); 0087 0088 /** 0089 * Returns the name of the page widget item. 0090 */ 0091 QString name() const; 0092 0093 /** 0094 * Sets the header of the page widget item. 0095 * 0096 * If setHeader(QString()) is used, what is the default if the header 0097 * does not got set explicit, then the defined name() will also be used 0098 * for the header. 0099 * 0100 * For backward-compatibility, if setHeader("") is used, the header will be hidden 0101 * even if the @a KPageView::FaceType is something else then Tabbed. 0102 * This feature is deprecated since 5.52. use @c setHeaderVisible(false) instead. 0103 * 0104 * @param header Header of the page widget item. 0105 */ 0106 void setHeader(const QString &header); 0107 0108 /** 0109 * Returns the header of the page widget item. 0110 */ 0111 QString header() const; 0112 0113 /** 0114 * Sets the icon of the page widget item. 0115 * @param icon Icon of the page widget item. 0116 */ 0117 void setIcon(const QIcon &icon); 0118 0119 /** 0120 * Returns the icon of the page widget item. 0121 */ 0122 QIcon icon() const; 0123 0124 /** 0125 * Sets whether the page widget item is checkable in the view. 0126 * @param checkable True if the page widget is checkable, 0127 * otherwise false. 0128 */ 0129 void setCheckable(bool checkable); 0130 0131 /** 0132 * Returns whether the page widget item is checkable. 0133 */ 0134 bool isCheckable() const; 0135 0136 /** 0137 * Returns whether the page widget item is checked. 0138 */ 0139 bool isChecked() const; 0140 0141 /** 0142 * Returns whether the page widget item is enabled. 0143 */ 0144 bool isEnabled() const; 0145 0146 /** 0147 * Returns whether the page will show the header title 0148 * @since 5.52 0149 */ 0150 bool isHeaderVisible() const; 0151 0152 /** 0153 * Set whether the page should show the header title 0154 * @since 5.52 0155 */ 0156 void setHeaderVisible(bool visible); 0157 0158 public Q_SLOTS: 0159 /** 0160 * Sets whether the page widget item is enabled. 0161 */ 0162 void setEnabled(bool); 0163 0164 /** 0165 * Sets whether the page widget item is checked. 0166 */ 0167 void setChecked(bool checked); 0168 0169 Q_SIGNALS: 0170 /** 0171 * This signal is emitted whenever the icon or header 0172 * is changed. 0173 */ 0174 void changed(); 0175 0176 /** 0177 * This signal is emitted whenever the user checks or 0178 * unchecks the item of setChecked() is called. 0179 */ 0180 void toggled(bool checked); 0181 0182 private: 0183 std::unique_ptr<class KPageWidgetItemPrivate> const d; 0184 }; 0185 0186 class KPageWidgetModelPrivate; 0187 0188 /** 0189 * @class KPageWidgetModel kpagewidgetmodel.h KPageWidgetModel 0190 * 0191 * This page model is used by KPageWidget to provide 0192 * a hierarchical layout of pages. 0193 */ 0194 class KWIDGETSADDONS_EXPORT KPageWidgetModel : public KPageModel 0195 { 0196 Q_OBJECT 0197 Q_DECLARE_PRIVATE(KPageWidgetModel) 0198 0199 public: 0200 /** 0201 * Creates a new page widget model. 0202 * 0203 * @param parent The parent object. 0204 */ 0205 explicit KPageWidgetModel(QObject *parent = nullptr); 0206 0207 /** 0208 * Destroys the page widget model. 0209 */ 0210 ~KPageWidgetModel() override; 0211 0212 /** 0213 * Adds a new top level page to the model. 0214 * 0215 * @param widget The widget of the page. 0216 * @param name The name which is displayed in the navigation view. 0217 * 0218 * @returns The associated KPageWidgetItem. 0219 */ 0220 KPageWidgetItem *addPage(QWidget *widget, const QString &name); 0221 0222 /** 0223 * Adds a new top level page to the model. 0224 * 0225 * @param item The KPageWidgetItem which describes the page. 0226 */ 0227 void addPage(KPageWidgetItem *item); 0228 0229 /** 0230 * Inserts a new page in the model. 0231 * 0232 * @param before The new page will be insert before this KPageWidgetItem 0233 * on the same level in hierarchy. 0234 * @param widget The widget of the page. 0235 * @param name The name which is displayed in the navigation view. 0236 * 0237 * @returns The associated KPageWidgetItem. 0238 */ 0239 KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name); 0240 0241 /** 0242 * Inserts a new page in the model. 0243 * 0244 * @param before The new page will be insert before this KPageWidgetItem 0245 * on the same level in hierarchy. 0246 * 0247 * @param item The KPageWidgetItem which describes the page. 0248 */ 0249 void insertPage(KPageWidgetItem *before, KPageWidgetItem *item); 0250 0251 /** 0252 * Inserts a new sub page in the model. 0253 * 0254 * @param parent The new page will be insert as child of this KPageWidgetItem. 0255 * @param widget The widget of the page. 0256 * @param name The name which is displayed in the navigation view. 0257 * 0258 * @returns The associated KPageWidgetItem. 0259 */ 0260 KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name); 0261 0262 /** 0263 * Inserts a new sub page in the model. 0264 * 0265 * @param parent The new page will be insert as child of this KPageWidgetItem. 0266 * 0267 * @param item The KPageWidgetItem which describes the page. 0268 */ 0269 void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item); 0270 0271 /** 0272 * Removes the page associated with the given KPageWidgetItem. 0273 */ 0274 void removePage(KPageWidgetItem *item); 0275 0276 /** 0277 * These methods are reimplemented from QAbstractItemModel. 0278 */ 0279 int columnCount(const QModelIndex &parent = QModelIndex()) const override; 0280 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override; 0281 bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override; 0282 Qt::ItemFlags flags(const QModelIndex &index) const override; 0283 QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override; 0284 QModelIndex parent(const QModelIndex &index) const override; 0285 int rowCount(const QModelIndex &parent = QModelIndex()) const override; 0286 0287 /** 0288 * Returns the KPageWidgetItem for a given index or a null pointer if the index is invalid. 0289 */ 0290 KPageWidgetItem *item(const QModelIndex &index) const; 0291 0292 /** 0293 * Returns the index for a given KPageWidgetItem. The index is invalid if the 0294 * item can't be found in the model. 0295 */ 0296 QModelIndex index(const KPageWidgetItem *item) const; 0297 0298 Q_SIGNALS: 0299 /** 0300 * This signal is emitted whenever a checkable page changes its state. @param checked is true 0301 * when the @p page is checked, or false if the @p page is unchecked. 0302 */ 0303 void toggled(KPageWidgetItem *page, bool checked); 0304 0305 private: 0306 Q_PRIVATE_SLOT(d_func(), void _k_itemChanged()) 0307 Q_PRIVATE_SLOT(d_func(), void _k_itemToggled(bool)) 0308 }; 0309 0310 #endif