File indexing completed on 2023-11-26 10:45:35

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2000 Waldo Bastian <bastian@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-only
0006 */
0007 
0008 #ifndef KSERVICEGROUP_H
0009 #define KSERVICEGROUP_H
0010 
0011 #include <kservice.h>
0012 #include <kservice_export.h>
0013 
0014 class KBuildServiceGroupFactory;
0015 
0016 class KServiceGroupPrivate;
0017 
0018 /**
0019  * @class KServiceGroup kservicegroup.h <KServiceGroup>
0020  *
0021  * KServiceGroup represents a group of service, for example
0022  * screensavers.
0023  * This class is typically used like this:
0024  *
0025  * \code
0026  * // Start from root group
0027  * KServiceGroup::Ptr group = KServiceGroup::root();
0028  * if (!group || !group->isValid()) return;
0029  *
0030  * KServiceGroup::List list = group->entries();
0031  *
0032  * // Iterate over all entries in the group
0033  * for( KServiceGroup::List::ConstIterator it = list.begin();
0034  *      it != list.end(); it++)
0035  * {
0036  *    KSycocaEntry *p = (*it);
0037  *    if (p->isType(KST_KService))
0038  *    {
0039  *       KService *s = static_cast<KService *>(p);
0040  *       printf("Name = %s\n", s->name().toLatin1());
0041  *    }
0042  *    else if (p->isType(KST_KServiceGroup))
0043  *    {
0044  *       KServiceGroup *g = static_cast<KServiceGroup *>(p);
0045  *       // Sub group ...
0046  *    }
0047  * }
0048  * \endcode
0049  *
0050  * @short Represents a group of services
0051  */
0052 class KSERVICE_EXPORT KServiceGroup : public KSycocaEntry
0053 {
0054     friend class KBuildServiceGroupFactory;
0055 
0056 public:
0057     /**
0058      * A shared data pointer for KServiceGroup.
0059      */
0060     typedef QExplicitlySharedDataPointer<KServiceGroup> Ptr;
0061     /**
0062      * A shared data pointer for KSycocaEntry.
0063      */
0064     typedef QExplicitlySharedDataPointer<KSycocaEntry> SPtr;
0065     /**
0066      * A list of shared data pointers for KSycocaEntry.
0067      */
0068     typedef QList<SPtr> List;
0069 
0070 public:
0071     /**
0072      * Construct a dummy servicegroup indexed with @p name.
0073      * @param name the name of the service group
0074      */
0075     KServiceGroup(const QString &name);
0076 
0077     /**
0078      * Construct a service and take all information from a config file
0079      * @param _fullpath full path to the config file
0080      * @param _relpath relative path to the config file
0081      */
0082     KServiceGroup(const QString &_fullpath, const QString &_relpath);
0083 
0084     ~KServiceGroup() override;
0085 
0086     /**
0087      * Returns the relative path of the service group.
0088      * @return the service group's relative path
0089      */
0090     QString relPath() const;
0091 
0092     /**
0093      * Returns the caption of this group.
0094      * @return the caption of this group
0095      */
0096     QString caption() const;
0097 
0098     /**
0099      * Returns the name of the icon associated with the group.
0100      * @return the name of the icon associated with the group,
0101      *         or QString() if not set
0102      */
0103     QString icon() const;
0104 
0105     /**
0106      * Returns the comment about this service group.
0107      * @return the descriptive comment for the group, if there is one,
0108      *         or QString() if not set
0109      */
0110     QString comment() const;
0111 
0112     /**
0113      * Returns the total number of displayable services in this group and
0114      * any of its subgroups.
0115      * @return the number of child services
0116      */
0117     int childCount() const;
0118 
0119     /**
0120      * Returns true if the NoDisplay flag was set, i.e. if this
0121      * group should be hidden from menus, while still being in ksycoca.
0122      * @return true to hide this service group, false to display it
0123      */
0124     bool noDisplay() const;
0125 
0126     /**
0127      * Return true if we want to display empty menu entry
0128      * @return true to show this service group as menu entry is empty, false to hide it
0129      */
0130     bool showEmptyMenu() const;
0131     void setShowEmptyMenu(bool b);
0132 
0133     /**
0134      * @return true to show an inline header into menu
0135      */
0136     bool showInlineHeader() const;
0137     void setShowInlineHeader(bool _b);
0138 
0139     /**
0140      * @return true to show an inline alias item into menu
0141      */
0142     bool inlineAlias() const;
0143     void setInlineAlias(bool _b);
0144     /**
0145      * @return true if we allow to inline menu.
0146      */
0147     bool allowInline() const;
0148     void setAllowInline(bool _b);
0149 
0150     /**
0151      * @return inline limit value
0152      */
0153     int inlineValue() const;
0154     void setInlineValue(int _val);
0155 
0156     /**
0157      * Returns a list of untranslated generic names that should be
0158      * be suppressed when showing this group.
0159      * E.g. The group "Games/Arcade" might want to suppress the generic name
0160      * "Arcade Game" since it's redundant in this particular context.
0161      */
0162     QStringList suppressGenericNames() const;
0163 
0164     /**
0165      * @internal
0166      * Sets information related to the layout of services in this group.
0167      */
0168     void setLayoutInfo(const QStringList &layout);
0169 
0170     /**
0171      * @internal
0172      * Returns information related to the layout of services in this group.
0173      */
0174     QStringList layoutInfo() const;
0175 
0176     /**
0177      * List of all Services and ServiceGroups within this
0178      * ServiceGroup.
0179      * @param sorted true to sort items
0180      * @param excludeNoDisplay true to exclude items marked "NoDisplay"
0181      * @param allowSeparators true to allow separator items to be included
0182      * @param sortByGenericName true to sort GenericName+Name instead of Name+GenericName
0183      * @return the list of entries
0184      */
0185     List entries(bool sorted, bool excludeNoDisplay, bool allowSeparators, bool sortByGenericName = false);
0186     List entries(bool sorted, bool excludeNoDisplay);
0187 
0188     /**
0189      * List of all Services and ServiceGroups within this
0190      * ServiceGroup.
0191      * @param sorted true to sort items
0192      * @return the list of entried
0193      */
0194     List entries(bool sorted = false);
0195 
0196     /**
0197      * options for groupEntries and serviceEntries
0198      * @see EntriesOptions
0199      */
0200     enum EntriesOption {
0201         NoOptions = 0x0, /**< no options set */
0202         SortEntries = 0x1, /**< sort items */
0203         ExcludeNoDisplay = 0x2, /**< exclude items marked "NoDisplay" */
0204         AllowSeparators = 0x4, /**< allow separator items to be included */
0205         SortByGenericName = 0x8, /**< sort by GenericName+Name instead of Name+GenericName */
0206     };
0207     /**
0208      * Stores a combination of #EntriesOption values.
0209      */
0210     Q_DECLARE_FLAGS(EntriesOptions, EntriesOption)
0211 
0212     /**
0213      * subgroups for this service group
0214      */
0215     QList<Ptr> groupEntries(EntriesOptions options = ExcludeNoDisplay);
0216 
0217     /**
0218      * entries of this service group
0219      */
0220     KService::List serviceEntries(EntriesOptions options = ExcludeNoDisplay);
0221 
0222     /**
0223      * Returns a non-empty string if the group is a special base group.
0224      * By default, "Settings/" is the kcontrol base group ("settings")
0225      * and "System/Screensavers/" is the screensavers base group ("screensavers").
0226      * This allows moving the groups without breaking those apps.
0227      *
0228      * The base group is defined by the X-KDE-BaseGroup key
0229      * in the .directory file.
0230      * @return the base group name, or null if no base group
0231      */
0232     QString baseGroupName() const;
0233 
0234     /**
0235      * Returns a path to the .directory file describing this service group.
0236      * The path is either absolute or relative to the "apps" resource.
0237      */
0238     QString directoryEntryPath() const;
0239 
0240     /**
0241      * Returns the root service group.
0242      * @return the root service group
0243      */
0244     static Ptr root();
0245 
0246     /**
0247      * Returns the group with the given relative path.
0248      * @param relPath the path of the service group
0249      * @return the group with the given relative path name.
0250      */
0251     static Ptr group(const QString &relPath);
0252 
0253     /**
0254      * Returns the group of services that have X-KDE-ParentApp equal
0255      * to @p parent (siblings).
0256      * @param parent the name of the service's parent
0257      * @return the services group
0258      */
0259     static Ptr childGroup(const QString &parent);
0260 
0261 protected:
0262     /**
0263      * @internal
0264      * Add a service to this group
0265      */
0266     void addEntry(const KSycocaEntry::Ptr &entry);
0267 
0268 private:
0269     friend class KServiceGroupFactory;
0270     /**
0271      * @internal construct a service from a stream.
0272      * The stream must already be positioned at the correct offset
0273      */
0274     KSERVICE_NO_EXPORT KServiceGroup(QDataStream &_str, int offset, bool deep);
0275 
0276     Q_DECLARE_PRIVATE(KServiceGroup)
0277 };
0278 
0279 #endif