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

0001 /*
0002  *   This file is part of the KDE project
0003  *   SPDX-FileCopyrightText: 2007 Will Stephenson <wstephenson@kde.org>
0004  *   SPDX-FileCopyrightText: 2009 Ben Cooksley <bcooksley@kde.org>
0005  *
0006  *   SPDX-License-Identifier: GPL-2.0-or-later
0007  */
0008 
0009 #ifndef MENUITEM_H
0010 #define MENUITEM_H
0011 
0012 #include <KService>
0013 
0014 #include "systemsettingsview_export.h"
0015 
0016 class QString;
0017 class KDesktopFile;
0018 class KPluginMetaData;
0019 template<typename T> class QList;
0020 
0021 /**
0022  * @brief Provides a specific item in the list of modules or categories
0023  *
0024  * This provides convenient access to the list of modules, providing information about them
0025  * such as name, module information and its service object.\n
0026  * This is created automatically by System Settings, and is shared among all plugins and so should not
0027  * be modified under any circumstances.\n
0028  *
0029  * System Settings creates it in a tree like manner, with categories containing subcategories and modules,
0030  * and subcategories repeating this.\n
0031  *
0032  * The service object must be set, unless it is the top level item, otherwise using applications
0033  * will crash when attempting to sort the children by weight
0034  *
0035  * @author Ben Cooksley <bcooksley@kde.org>
0036  * @author Will Stephenson <wstephenson@kde.org>
0037  */
0038 class SYSTEMSETTINGSVIEW_EXPORT MenuItem
0039 {
0040 public:
0041     /**
0042      * Creates a MenuItem.
0043      * @note Will not provide keywords, name, or a module item until a service has been set.
0044      *
0045      * @param isMenu Specifies if it is a category or not.
0046      * @param parent The item it is parented to. Provide 0 for a top level item.
0047      */
0048     MenuItem(bool isMenu, MenuItem *parent);
0049 
0050     /**
0051      * Destroys a MenuItem, including all children, the service object and the module information.
0052      *
0053      * @warning Destroys the KService and KCModuleInfo objects provided by service() and item().
0054      */
0055     ~MenuItem();
0056 
0057     /**
0058      * Sorts the children depending on the value of "X-KDE-Weight" in the desktop files of the
0059      * category or module.
0060      */
0061     void sortChildrenByWeight();
0062 
0063     /**
0064      * Provides the MenuItem for the child at the specified index.
0065      *
0066      * @param index The index of the child.
0067      * @returns The MenuItem object of the specified child.
0068      */
0069     MenuItem *child(int index);
0070 
0071     /**
0072      * Returns the list of keywords, which is used for searching the list of categories and modules.
0073      *
0074      * @note The parent items share all the keywords of their children.
0075      *
0076      * @param doesRemoveDuplicates Whether to remove duplicate keywords from the list.
0077      * @returns The list of keywords the item has.
0078      */
0079     QStringList keywords(bool doesRemoveDuplicates = true) const;
0080 
0081     /**
0082      * Returns the parent of this item.
0083      *
0084      * @returns The MenuItem object of this items parent.
0085      */
0086     MenuItem *parent() const;
0087 
0088     /**
0089      * Provides a list of all the children of this item.
0090      *
0091      * @returns The list of children this has.
0092      */
0093     QList<MenuItem *> &children() const;
0094 
0095     /**
0096      * @return comment of service or description of KPluginMetaData
0097      */
0098     QString comment() const;
0099 
0100     /**
0101      * @return icon of service or iconName of KPluginMetaData
0102      */
0103     QString iconName() const;
0104 
0105     bool isExternalAppModule() const;
0106 
0107     bool isSystemsettingsCategory() const;
0108     QString systemsettingsCategoryModule() const;
0109     bool isSystemsettingsRootCategory() const;
0110 
0111     /**
0112      * @return true if module represents a KCM plugin
0113      */
0114     bool isLibrary();
0115 
0116     /**
0117      * Convenience function which provides the name of the current item.
0118      *
0119      * @returns The name of the item, if the service object has been set.
0120      */
0121     QString &name() const;
0122 
0123     /**
0124      * Convenience function which provides the System Settings category of the current item.
0125      *
0126      * @returns The category of the item, if the service object has been set.
0127      */
0128     QString &category() const;
0129 
0130     /**
0131      * Provides the weight of the current item, as determined by its service.
0132      * If the service does not specify a weight, it is 100
0133      *
0134      * @returns The weight of the service
0135      */
0136     int weight();
0137 
0138     /**
0139      * Provides information on which type the current item is.
0140      *
0141      * @returns true if it is a category.
0142      * @returns false if it is not a category.
0143      */
0144     bool menu() const;
0145 
0146     /**
0147      * Constructs an item which resembles a category using the given filename.
0148      * The properties are read using KConfig
0149      */
0150     void setCategoryConfig(const KDesktopFile &file);
0151 
0152     /**
0153      * Constructs an item which resembles a category using the meta data.
0154      * This method is preferred to setService(const KService &service)
0155      */
0156     void setMetaData(const KPluginMetaData &data);
0157 
0158     KPluginMetaData metaData();
0159 
0160     MenuItem *descendantForModule(const QString &moduleName);
0161 
0162     bool showDefaultIndicator() const;
0163 
0164     void updateDefaultIndicator();
0165 
0166     void setDefaultIndicator(bool defaultIndicator);
0167     
0168     /**
0169      * If true this is the main module of this category and should appear in a more prominent way compared to the others
0170      */
0171     bool isCategoryOwner() const;
0172     void setCategoryOwner(bool owner);
0173 
0174 private:
0175     class Private;
0176     Private *const d;
0177 };
0178 
0179 Q_DECLARE_METATYPE(MenuItem *)
0180 
0181 #endif