File indexing completed on 2025-04-20 13:30:39
0001 /* 0002 * SPDX-FileCopyrightText: 2009 Ben Cooksley <bcooksley@kde.org> 0003 * SPDX-FileCopyrightText: 2007 Will Stephenson <wstephenson@kde.org> 0004 * 0005 * SPDX-License-Identifier: GPL-2.0-or-later 0006 */ 0007 0008 #ifndef MENUMODEL_H 0009 #define MENUMODEL_H 0010 0011 #include <QAbstractItemModel> 0012 0013 #include "systemsettingsview_export.h" 0014 0015 class MenuItem; 0016 0017 /** 0018 * @brief Provides a menu of the MenuItem objects 0019 * 0020 * Provides a standardised model to be used with views to display the list of modules in a variety of ways.\n 0021 * It is recommended to also use this with the MenuProxyModel to provide searching 0022 * and correct ordering of modules. 0023 * 0024 * @author Ben Cooksley <bcooksley@kde.org> 0025 * @author Will Stephenson <wstephenson@kde.org> 0026 */ 0027 class SYSTEMSETTINGSVIEW_EXPORT MenuModel : public QAbstractItemModel 0028 { 0029 Q_OBJECT 0030 0031 public: 0032 enum Roles { 0033 MenuItemRole = Qt::UserRole, 0034 0035 /** 0036 * Role used to request the keywords to filter the items when searching. 0037 */ 0038 UserFilterRole, 0039 0040 /** 0041 * Role used to request the weight of a module, used to sort the items. 0042 */ 0043 UserSortRole, 0044 0045 DepthRole, 0046 0047 IsCategoryRole, 0048 0049 IsKCMRole, 0050 0051 DefaultIndicatorRole, 0052 0053 IconNameRole, 0054 }; 0055 0056 /** 0057 * Creates a MenuModel using the MenuItem specified. The MenuItem must always be valid 0058 * throughout the life of the MenuModel, otherwise it will cause crashes. 0059 * 0060 * @param menuRoot The MenuItem to use as the basis for providing information. 0061 * @param parent The QObject to use as a parent of the MenuModel. 0062 */ 0063 explicit MenuModel(MenuItem *menuRoot, QObject *parent = nullptr); 0064 0065 /** 0066 * Destroys the MenuModel. The menuRoot will not be destroyed. 0067 */ 0068 ~MenuModel() override; 0069 0070 QHash<int, QByteArray> roleNames() const override; 0071 0072 /** 0073 * Please see Qt QAbstractItemModel documentation for more details.\n 0074 * Provides the name, tooltip, icon, category, keywords and the internal MenuItem to views. 0075 * 0076 * @param index The QModelIndex you want information about. 0077 * @param role The information role you want information about. 0078 * @returns The data requested for the role provided from the QModelIndex provided. 0079 */ 0080 QVariant data(const QModelIndex &index, int role) const override; 0081 0082 /** 0083 * Please see Qt QAbstractItemModel documentation for more details.\n 0084 * Provides the status flags for the QModelIndex specified. 0085 * The item always has selectable and enabled for its status unless invalid. 0086 * 0087 * @returns The flags for the QModelIndex provided. 0088 */ 0089 Qt::ItemFlags flags(const QModelIndex &index) const override; 0090 0091 /** 0092 * Please see Qt QAbstractItemModel documentation for more details.\n 0093 * Provides a QModelIndex at the row and column specified who belongs to the parent specified. 0094 * 0095 * @param row Vertical position in the grid of children. 0096 * @param column Horizontal position in the grid of children. 0097 * @param parent The parent of the requested child. 0098 * @returns The QModelIndex for the item requested. 0099 */ 0100 QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override; 0101 0102 /** 0103 * Please see Qt QAbstractItemModel documentation for more details.\n 0104 * Provides the parent QModelIndex for the child specified. 0105 * 0106 * @param index The child of the parent. 0107 * @returns A QModelIndex for the parent. 0108 */ 0109 QModelIndex parent(const QModelIndex &index) const override; 0110 0111 /** 0112 * Please see Qt QAbstractItemModel documentation for more details.\n 0113 * Provides the number of MenuItems ( categories or modules ) that the specified parent has. 0114 * 0115 * @param parent The QModelIndex the count is performed on. 0116 * @returns The number of rows ( children ) in the parent. 0117 */ 0118 int rowCount(const QModelIndex &parent = QModelIndex()) const override; 0119 0120 /** 0121 * Please see Qt QAbstractItemModel documentation for more details.\n 0122 * Returns 1, the number of columns of information about a row. 0123 * 0124 * @param parent This is ignored, as the count is always 1. 0125 * @returns The number of columns ( 1 ) in the parent. 0126 */ 0127 int columnCount(const QModelIndex &parent = QModelIndex()) const override; 0128 0129 /** 0130 * Makes the MenuItem specified be hidden from the list, while still showing its children.\n 0131 * Children of exceptions consider their grand parents as their parent. 0132 * Parents of exceptions consider the exceptions children as theirs. 0133 * 0134 * @param exception The MenuItem to give an exception to. 0135 */ 0136 void addException(MenuItem *exception); 0137 0138 /** 0139 * Revokes the exception granted above. After this, the MenuItem's parents will return their children 0140 * as normal and the grand children will return their true parents, restoring normal operation. 0141 * It has no effect if the MenuItem does not have an exception. 0142 * 0143 * @param exception The MenuItem to revoke an exception from. 0144 */ 0145 void removeException(MenuItem *exception); 0146 0147 QModelIndex indexForItem(MenuItem *item) const; 0148 0149 protected: 0150 /** 0151 * Provides the MenuItem which is used internally to provide information. 0152 * 0153 * @returns The MenuItem used internally. 0154 */ 0155 MenuItem *rootItem() const; 0156 0157 /** 0158 * Provides a list of children of an item which has been altered by the exceptions list 0159 * 0160 * @param parent The parent of the children desired 0161 * @returns The list of children for the item specified 0162 */ 0163 QList<MenuItem *> childrenList(MenuItem *parent) const; 0164 0165 /** 0166 * Provides the parent of the child specified altered by the exceptions list 0167 * 0168 * @param child The child of the parent 0169 * @returns The exceptions list affected parent of the child 0170 */ 0171 MenuItem *parentItem(MenuItem *child) const; 0172 0173 private: 0174 class Private; 0175 Private *const d; 0176 }; 0177 0178 #endif