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 KPAGEWIDGETMODEL_H 9 #define KPAGEWIDGETMODEL_H 10 11 #include "kpagemodel.h" 12 #include <memory> 13 14 class QWidget; 15 16 /** 17 * @class KPageWidgetItem kpagewidgetmodel.h KPageWidgetItem 18 * 19 * KPageWidgetItem is used by @ref KPageWidget and represents 20 * a page. 21 * 22 * <b>Example:</b>\n 23 * 24 * \code 25 * ColorPage *page = new ColorPage; 26 * 27 * KPageWidgetItem *item = new KPageWidgetItem( page, i18n( "Colors" ) ); 28 * item->setHeader( i18n( "Colors of Main Window" ) ); 29 * item->setIcon( QIcon::fromTheme( "colors" ) ); 30 * 31 * KPageWidget *pageWidget = new KPageWidget( this ); 32 * pageWidget->addPage( item ); 33 * \endcode 34 * 35 * @author Tobias Koenig (tokoe@kde.org) 36 */ 37 class KWIDGETSADDONS_EXPORT KPageWidgetItem : public QObject 38 { 39 Q_OBJECT 40 Q_PROPERTY(QString name READ name WRITE setName) 41 Q_PROPERTY(QString header READ header WRITE setHeader) 42 Q_PROPERTY(QIcon icon READ icon WRITE setIcon) 43 Q_PROPERTY(bool checkable READ isCheckable WRITE setCheckable) 44 Q_PROPERTY(bool checked READ isChecked WRITE setChecked) 45 /** 46 * This property holds whether the item is enabled. 47 * 48 * It dis-/enables both the widget and the item in the list-/treeview. 49 */ 50 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled) 51 /** 52 * @since 5.52 53 */ 54 Q_PROPERTY(bool headerVisible READ isHeaderVisible WRITE setHeaderVisible) 55 public: 56 /** 57 * Creates a new page widget item. 58 * 59 * @param widget The widget that is shown as page in the KPageWidget. 60 */ 61 KPageWidgetItem(QWidget *widget); 62 63 /** 64 * Creates a new page widget item. 65 * 66 * @param widget The widget that is shown as page in the KPageWidget. 67 * @param name The localized string that is show in the navigation view 68 * of the KPageWidget. 69 */ 70 KPageWidgetItem(QWidget *widget, const QString &name); 71 72 /** 73 * Destroys the page widget item. 74 */ 75 ~KPageWidgetItem() override; 76 77 /** 78 * Returns the widget of the page widget item. 79 */ 80 QWidget *widget() const; 81 82 /** 83 * Sets the name of the item as shown in the navigation view of the page 84 * widget. 85 */ 86 void setName(const QString &name); 87 88 /** 89 * Returns the name of the page widget item. 90 */ 91 QString name() const; 92 93 /** 94 * Sets the header of the page widget item. 95 * 96 * If setHeader(QString()) is used, what is the default if the header 97 * does not got set explicit, then the defined name() will also be used 98 * for the header. 99 * 100 * For backward-compatibility, if setHeader("") is used, the header will be hidden 101 * even if the @a KPageView::FaceType is something else then Tabbed. 102 * This feature is deprecated since 5.52. use @c setHeaderVisible(false) instead. 103 * 104 * @param header Header of the page widget item. 105 */ 106 void setHeader(const QString &header); 107 108 /** 109 * Returns the header of the page widget item. 110 */ 111 QString header() const; 112 113 /** 114 * Sets the icon of the page widget item. 115 * @param icon Icon of the page widget item. 116 */ 117 void setIcon(const QIcon &icon); 118 119 /** 120 * Returns the icon of the page widget item. 121 */ 122 QIcon icon() const; 123 124 /** 125 * Sets whether the page widget item is checkable in the view. 126 * @param checkable True if the page widget is checkable, 127 * otherwise false. 128 */ 129 void setCheckable(bool checkable); 130 131 /** 132 * Returns whether the page widget item is checkable. 133 */ 134 bool isCheckable() const; 135 136 /** 137 * Returns whether the page widget item is checked. 138 */ 139 bool isChecked() const; 140 141 /** 142 * Returns whether the page widget item is enabled. 143 */ 144 bool isEnabled() const; 145 146 /** 147 * Returns whether the page will show the header title 148 * @since 5.52 149 */ 150 bool isHeaderVisible() const; 151 152 /** 153 * Set whether the page should show the header title 154 * @since 5.52 155 */ 156 void setHeaderVisible(bool visible); 157 158 public Q_SLOTS: 159 /** 160 * Sets whether the page widget item is enabled. 161 */ 162 void setEnabled(bool); 163 164 /** 165 * Sets whether the page widget item is checked. 166 */ 167 void setChecked(bool checked); 168 169 Q_SIGNALS: 170 /** 171 * This signal is emitted whenever the icon or header 172 * is changed. 173 */ 174 void changed(); 175 176 /** 177 * This signal is emitted whenever the user checks or 178 * unchecks the item of setChecked() is called. 179 */ 180 void toggled(bool checked); 181 182 private: 183 std::unique_ptr<class KPageWidgetItemPrivate> const d; 184 }; 185 186 class KPageWidgetModelPrivate; 187 188 /** 189 * @class KPageWidgetModel kpagewidgetmodel.h KPageWidgetModel 190 * 191 * This page model is used by KPageWidget to provide 192 * a hierarchical layout of pages. 193 */ 194 class KWIDGETSADDONS_EXPORT KPageWidgetModel : public KPageModel 195 { 196 Q_OBJECT 197 Q_DECLARE_PRIVATE(KPageWidgetModel) 198 199 public: 200 /** 201 * Creates a new page widget model. 202 * 203 * @param parent The parent object. 204 */ 205 explicit KPageWidgetModel(QObject *parent = nullptr); 206 207 /** 208 * Destroys the page widget model. 209 */ 210 ~KPageWidgetModel() override; 211 212 /** 213 * Adds a new top level page to the model. 214 * 215 * @param widget The widget of the page. 216 * @param name The name which is displayed in the navigation view. 217 * 218 * @returns The associated KPageWidgetItem. 219 */ 220 KPageWidgetItem *addPage(QWidget *widget, const QString &name); 221 222 /** 223 * Adds a new top level page to the model. 224 * 225 * @param item The KPageWidgetItem which describes the page. 226 */ 227 void addPage(KPageWidgetItem *item); 228 229 /** 230 * Inserts a new page in the model. 231 * 232 * @param before The new page will be insert before this KPageWidgetItem 233 * on the same level in hierarchy. 234 * @param widget The widget of the page. 235 * @param name The name which is displayed in the navigation view. 236 * 237 * @returns The associated KPageWidgetItem. 238 */ 239 KPageWidgetItem *insertPage(KPageWidgetItem *before, QWidget *widget, const QString &name); 240 241 /** 242 * Inserts a new page in the model. 243 * 244 * @param before The new page will be insert before this KPageWidgetItem 245 * on the same level in hierarchy. 246 * 247 * @param item The KPageWidgetItem which describes the page. 248 */ 249 void insertPage(KPageWidgetItem *before, KPageWidgetItem *item); 250 251 /** 252 * Inserts a new sub page in the model. 253 * 254 * @param parent The new page will be insert as child of this KPageWidgetItem. 255 * @param widget The widget of the page. 256 * @param name The name which is displayed in the navigation view. 257 * 258 * @returns The associated KPageWidgetItem. 259 */ 260 KPageWidgetItem *addSubPage(KPageWidgetItem *parent, QWidget *widget, const QString &name); 261 262 /** 263 * Inserts a new sub page in the model. 264 * 265 * @param parent The new page will be insert as child of this KPageWidgetItem. 266 * 267 * @param item The KPageWidgetItem which describes the page. 268 */ 269 void addSubPage(KPageWidgetItem *parent, KPageWidgetItem *item); 270 271 /** 272 * Removes the page associated with the given KPageWidgetItem. 273 */ 274 void removePage(KPageWidgetItem *item); 275 276 /** 277 * These methods are reimplemented from QAbstractItemModel. 278 */ 279 int columnCount(const QModelIndex &parent = QModelIndex()) const override; 280 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override; 281 bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override; 282 Qt::ItemFlags flags(const QModelIndex &index) const override; 283 QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override; 284 QModelIndex parent(const QModelIndex &index) const override; 285 int rowCount(const QModelIndex &parent = QModelIndex()) const override; 286 287 /** 288 * Returns the KPageWidgetItem for a given index or a null pointer if the index is invalid. 289 */ 290 KPageWidgetItem *item(const QModelIndex &index) const; 291 292 /** 293 * Returns the index for a given KPageWidgetItem. The index is invalid if the 294 * item can't be found in the model. 295 */ 296 QModelIndex index(const KPageWidgetItem *item) const; 297 298 Q_SIGNALS: 299 /** 300 * This signal is emitted whenever a checkable page changes its state. @param checked is true 301 * when the @p page is checked, or false if the @p page is unchecked. 302 */ 303 void toggled(KPageWidgetItem *page, bool checked); 304 305 private: 306 Q_PRIVATE_SLOT(d_func(), void _k_itemChanged()) 307 Q_PRIVATE_SLOT(d_func(), void _k_itemToggled(bool)) 308 }; 309 310 #endif 311