File indexing completed on 2024-04-28 03:59:11
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 * @param header Header of the page widget item. 0101 */ 0102 void setHeader(const QString &header); 0103 0104 /** 0105 * Returns the header of the page widget item. 0106 */ 0107 QString header() const; 0108 0109 /** 0110 * Sets the icon of the page widget item. 0111 * @param icon Icon of the page widget item. 0112 */ 0113 void setIcon(const QIcon &icon); 0114 0115 /** 0116 * Returns the icon of the page widget item. 0117 */ 0118 QIcon icon() const; 0119 0120 /** 0121 * Sets whether the page widget item is checkable in the view. 0122 * @param checkable True if the page widget is checkable, 0123 * otherwise false. 0124 */ 0125 void setCheckable(bool checkable); 0126 0127 /** 0128 * Returns whether the page widget item is checkable. 0129 */ 0130 bool isCheckable() const; 0131 0132 /** 0133 * Returns whether the page widget item is checked. 0134 */ 0135 bool isChecked() const; 0136 0137 /** 0138 * Returns whether the page widget item is enabled. 0139 */ 0140 bool isEnabled() const; 0141 0142 /** 0143 * Returns whether the page will show the header title 0144 * @since 5.52 0145 */ 0146 bool isHeaderVisible() const; 0147 0148 /** 0149 * Set whether the page should show the header title 0150 * @since 5.52 0151 */ 0152 void setHeaderVisible(bool visible); 0153 0154 public Q_SLOTS: 0155 /** 0156 * Sets whether the page widget item is enabled. 0157 */ 0158 void setEnabled(bool); 0159 0160 /** 0161 * Sets whether the page widget item is checked. 0162 */ 0163 void setChecked(bool checked); 0164 0165 Q_SIGNALS: 0166 /** 0167 * This signal is emitted whenever the icon or header 0168 * is changed. 0169 */ 0170 void changed(); 0171 0172 /** 0173 * This signal is emitted whenever the user checks or 0174 * unchecks the item of setChecked() is called. 0175 */ 0176 void toggled(bool checked); 0177 0178 private: 0179 std::unique_ptr<class KPageWidgetItemPrivate> const d; 0180 }; 0181 0182 class KPageWidgetModelPrivate; 0183 0184 /** 0185 * @class KPageWidgetModel kpagewidgetmodel.h KPageWidgetModel 0186 * 0187 * This page model is used by KPageWidget to provide 0188 * a hierarchical layout of pages. 0189 */ 0190 class KWIDGETSADDONS_EXPORT KPageWidgetModel : public KPageModel 0191 { 0192 Q_OBJECT 0193 Q_DECLARE_PRIVATE(KPageWidgetModel) 0194 0195 public: 0196 /** 0197 * Creates a new page widget model. 0198 * 0199 * @param parent The parent object. 0200 */ 0201 explicit KPageWidgetModel(QObject *parent = nullptr); 0202 0203 /** 0204 * Destroys the page widget model. 0205 */ 0206 ~KPageWidgetModel() override; 0207 0208 /** 0209 * Adds a new top level page to the model. 0210 * 0211 * @param widget The widget of the page. 0212 * @param name The name which is displayed in the navigation view. 0213 * 0214 * @returns The associated KPageWidgetItem. 0215 */ 0216 KPageWidgetItem *addPage(QWidget *widget, const QString &name); 0217 0218 /** 0219 * Adds a new top level page to the model. 0220 * 0221 * @param item The KPageWidgetItem which describes the page. 0222 */ 0223 void addPage(KPageWidgetItem *item); 0224 0225 /** 0226 * Inserts a new page in the model. 0227 * 0228 * @param before The new page will be insert before this KPageWidgetItem 0229 * on the same level in hierarchy. 0230 * @param widget The widget of the page. 0231 * @param name The name which is displayed in the navigation view. 0232 * 0233 * @returns The associated KPageWidgetItem. 0234 */ 0235 KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name); 0236 0237 /** 0238 * Inserts a new page in the model. 0239 * 0240 * @param before The new page will be insert before this KPageWidgetItem 0241 * on the same level in hierarchy. 0242 * 0243 * @param item The KPageWidgetItem which describes the page. 0244 */ 0245 void insertPage(KPageWidgetItem *before, KPageWidgetItem *item); 0246 0247 /** 0248 * Inserts a new sub page in the model. 0249 * 0250 * @param parent The new page will be insert as child of this KPageWidgetItem. 0251 * @param widget The widget of the page. 0252 * @param name The name which is displayed in the navigation view. 0253 * 0254 * @returns The associated KPageWidgetItem. 0255 */ 0256 KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name); 0257 0258 /** 0259 * Inserts a new sub page in the model. 0260 * 0261 * @param parent The new page will be insert as child of this KPageWidgetItem. 0262 * 0263 * @param item The KPageWidgetItem which describes the page. 0264 */ 0265 void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item); 0266 0267 /** 0268 * Removes the page associated with the given KPageWidgetItem. 0269 */ 0270 void removePage(KPageWidgetItem *item); 0271 0272 /** 0273 * These methods are reimplemented from QAbstractItemModel. 0274 */ 0275 int columnCount(const QModelIndex &parent = QModelIndex()) const override; 0276 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override; 0277 bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override; 0278 Qt::ItemFlags flags(const QModelIndex &index) const override; 0279 QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override; 0280 QModelIndex parent(const QModelIndex &index) const override; 0281 int rowCount(const QModelIndex &parent = QModelIndex()) const override; 0282 0283 /** 0284 * Returns the KPageWidgetItem for a given index or a null pointer if the index is invalid. 0285 */ 0286 KPageWidgetItem *item(const QModelIndex &index) const; 0287 0288 /** 0289 * Returns the index for a given KPageWidgetItem. The index is invalid if the 0290 * item can't be found in the model. 0291 */ 0292 QModelIndex index(const KPageWidgetItem *item) const; 0293 0294 Q_SIGNALS: 0295 /** 0296 * This signal is emitted whenever a checkable page changes its state. @param checked is true 0297 * when the @p page is checked, or false if the @p page is unchecked. 0298 */ 0299 void toggled(KPageWidgetItem *page, bool checked); 0300 0301 private: 0302 Q_PRIVATE_SLOT(d_func(), void _k_itemChanged()) 0303 Q_PRIVATE_SLOT(d_func(), void _k_itemToggled(bool)) 0304 }; 0305 0306 #endif