File indexing completed on 2024-04-14 15:42:34

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