File indexing completed on 2024-12-01 03:42:11

 /*
     This file is part of the KDE project
     SPDX-FileCopyrightText: 2000 Waldo Bastian <bastian@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-only
 */
 
 #ifndef KSERVICEGROUP_H
 #define KSERVICEGROUP_H
 
 #include <kservice.h>
 #include <kservice_export.h>
 
 class KBuildServiceGroupFactory;
 
 class KServiceGroupPrivate;
 
 /**
  * @class KServiceGroup kservicegroup.h <KServiceGroup>
  *
  * KServiceGroup represents a group of service, for example
  * screensavers.
  * This class is typically used like this:
  *
  * \code
  * // Start from root group
  * KServiceGroup::Ptr group = KServiceGroup::root();
  * if (!group || !group->isValid()) return;
  *
  * KServiceGroup::List list = group->entries();
  *
  * // Iterate over all entries in the group
  * for( KServiceGroup::List::ConstIterator it = list.begin();
  *      it != list.end(); it++)
  * {
  *    KSycocaEntry *p = (*it);
  *    if (p->isType(KST_KService))
  *    {
  *       KService *s = static_cast<KService *>(p);
  *       printf("Name = %s\n", s->name().toLatin1());
  *    }
  *    else if (p->isType(KST_KServiceGroup))
  *    {
  *       KServiceGroup *g = static_cast<KServiceGroup *>(p);
  *       // Sub group ...
  *    }
  * }
  * \endcode
  *
  * @short Represents a group of services
  */
 class KSERVICE_EXPORT KServiceGroup : public KSycocaEntry
 {
     friend class KBuildServiceGroupFactory;
 
 public:
     /**
      * A shared data pointer for KServiceGroup.
      */
     typedef QExplicitlySharedDataPointer<KServiceGroup> Ptr;
     /**
      * A shared data pointer for KSycocaEntry.
      */
     typedef QExplicitlySharedDataPointer<KSycocaEntry> SPtr;
     /**
      * A list of shared data pointers for KSycocaEntry.
      */
     typedef QList<SPtr> List;
 
 public:
     /**
      * Construct a dummy servicegroup indexed with @p name.
      * @param name the name of the service group
      */
     KServiceGroup(const QString &name);
 
     /**
      * Construct a service and take all information from a config file
      * @param _fullpath full path to the config file
      * @param _relpath relative path to the config file
      */
     KServiceGroup(const QString &_fullpath, const QString &_relpath);
 
     ~KServiceGroup() override;
 
     /**
      * Returns the relative path of the service group.
      * @return the service group's relative path
      */
     QString relPath() const;
 
     /**
      * Returns the caption of this group.
      * @return the caption of this group
      */
     QString caption() const;
 
     /**
      * Returns the name of the icon associated with the group.
      * @return the name of the icon associated with the group,
      *         or QString() if not set
      */
     QString icon() const;
 
     /**
      * Returns the comment about this service group.
      * @return the descriptive comment for the group, if there is one,
      *         or QString() if not set
      */
     QString comment() const;
 
     /**
      * Returns the total number of displayable services in this group and
      * any of its subgroups.
      * @return the number of child services
      */
     int childCount() const;
 
     /**
      * Returns true if the NoDisplay flag was set, i.e. if this
      * group should be hidden from menus, while still being in ksycoca.
      * @return true to hide this service group, false to display it
      */
     bool noDisplay() const;
 
     /**
      * Return true if we want to display empty menu entry
      * @return true to show this service group as menu entry is empty, false to hide it
      */
     bool showEmptyMenu() const;
     void setShowEmptyMenu(bool b);
 
     /**
      * @return true to show an inline header into menu
      */
     bool showInlineHeader() const;
     void setShowInlineHeader(bool _b);
 
     /**
      * @return true to show an inline alias item into menu
      */
     bool inlineAlias() const;
     void setInlineAlias(bool _b);
     /**
      * @return true if we allow to inline menu.
      */
     bool allowInline() const;
     void setAllowInline(bool _b);
 
     /**
      * @return inline limit value
      */
     int inlineValue() const;
     void setInlineValue(int _val);
 
     /**
      * Returns a list of untranslated generic names that should be
      * be suppressed when showing this group.
      * E.g. The group "Games/Arcade" might want to suppress the generic name
      * "Arcade Game" since it's redundant in this particular context.
      */
     QStringList suppressGenericNames() const;
 
     /**
      * @internal
      * Sets information related to the layout of services in this group.
      */
     void setLayoutInfo(const QStringList &layout);
 
     /**
      * @internal
      * Returns information related to the layout of services in this group.
      */
     QStringList layoutInfo() const;
 
     /**
      * List of all Services and ServiceGroups within this
      * ServiceGroup.
      * @param sorted true to sort items
      * @param excludeNoDisplay true to exclude items marked "NoDisplay"
      * @param allowSeparators true to allow separator items to be included
      * @param sortByGenericName true to sort GenericName+Name instead of Name+GenericName
      * @return the list of entries
      */
     List entries(bool sorted, bool excludeNoDisplay, bool allowSeparators, bool sortByGenericName = false);
     List entries(bool sorted, bool excludeNoDisplay);
 
     /**
      * List of all Services and ServiceGroups within this
      * ServiceGroup.
      * @param sorted true to sort items
      * @return the list of entried
      */
     List entries(bool sorted = false);
 
     /**
      * options for groupEntries and serviceEntries
      * @see EntriesOptions
      */
     enum EntriesOption {
         NoOptions = 0x0, /**< no options set */
         SortEntries = 0x1, /**< sort items */
         ExcludeNoDisplay = 0x2, /**< exclude items marked "NoDisplay" */
         AllowSeparators = 0x4, /**< allow separator items to be included */
         SortByGenericName = 0x8, /**< sort by GenericName+Name instead of Name+GenericName */
     };
     /**
      * Stores a combination of #EntriesOption values.
      */
     Q_DECLARE_FLAGS(EntriesOptions, EntriesOption)
 
     /**
      * subgroups for this service group
      */
     QList<Ptr> groupEntries(EntriesOptions options = ExcludeNoDisplay);
 
     /**
      * entries of this service group
      */
     KService::List serviceEntries(EntriesOptions options = ExcludeNoDisplay);
 
     /**
      * Returns a non-empty string if the group is a special base group.
      * By default, "Settings/" is the kcontrol base group ("settings")
      * and "System/Screensavers/" is the screensavers base group ("screensavers").
      * This allows moving the groups without breaking those apps.
      *
      * The base group is defined by the X-KDE-BaseGroup key
      * in the .directory file.
      * @return the base group name, or null if no base group
      */
     QString baseGroupName() const;
 
     /**
      * Returns a path to the .directory file describing this service group.
      * The path is either absolute or relative to the "apps" resource.
      */
     QString directoryEntryPath() const;
 
     /**
      * Returns the root service group.
      * @return the root service group
      */
     static Ptr root();
 
     /**
      * Returns the group with the given relative path.
      * @param relPath the path of the service group
      * @return the group with the given relative path name.
      */
     static Ptr group(const QString &relPath);
 
     /**
      * Returns the group of services that have X-KDE-ParentApp equal
      * to @p parent (siblings).
      * @param parent the name of the service's parent
      * @return the services group
      */
     static Ptr childGroup(const QString &parent);
 
 protected:
     /**
      * @internal
      * Add a service to this group
      */
     void addEntry(const KSycocaEntry::Ptr &entry);
 
 private:
     friend class KServiceGroupFactory;
     /**
      * @internal construct a service from a stream.
      * The stream must already be positioned at the correct offset
      */
     KSERVICE_NO_EXPORT KServiceGroup(QDataStream &_str, int offset, bool deep);
 
     Q_DECLARE_PRIVATE(KServiceGroup)
 };
 
 #endif