File indexing completed on 2024-05-19 09:32:18

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