1 /* 2 This file is part of the KDE project 3 SPDX-FileCopyrightText: 2000 Waldo Bastian <bastian@kde.org> 4 5 SPDX-License-Identifier: LGPL-2.0-only 6 */ 7 8 #ifndef KSERVICEGROUP_H 9 #define KSERVICEGROUP_H 10 11 #include <kservice.h> 12 #include <kservice_export.h> 13 14 class KBuildServiceGroupFactory; 15 16 class KServiceGroupPrivate; 17 18 /** 19 * @class KServiceGroup kservicegroup.h <KServiceGroup> 20 * 21 * KServiceGroup represents a group of service, for example 22 * screensavers. 23 * This class is typically used like this: 24 * 25 * \code 26 * // Start from root group 27 * KServiceGroup::Ptr group = KServiceGroup::root(); 28 * if (!group || !group->isValid()) return; 29 * 30 * KServiceGroup::List list = group->entries(); 31 * 32 * // Iterate over all entries in the group 33 * for( KServiceGroup::List::ConstIterator it = list.begin(); 34 * it != list.end(); it++) 35 * { 36 * KSycocaEntry *p = (*it); 37 * if (p->isType(KST_KService)) 38 * { 39 * KService *s = static_cast<KService *>(p); 40 * printf("Name = %s\n", s->name().toLatin1()); 41 * } 42 * else if (p->isType(KST_KServiceGroup)) 43 * { 44 * KServiceGroup *g = static_cast<KServiceGroup *>(p); 45 * // Sub group ... 46 * } 47 * } 48 * \endcode 49 * 50 * @short Represents a group of services 51 */ 52 class KSERVICE_EXPORT KServiceGroup : public KSycocaEntry 53 { 54 friend class KBuildServiceGroupFactory; 55 56 public: 57 /** 58 * A shared data pointer for KServiceGroup. 59 */ 60 typedef QExplicitlySharedDataPointer<KServiceGroup> Ptr; 61 /** 62 * A shared data pointer for KSycocaEntry. 63 */ 64 typedef QExplicitlySharedDataPointer<KSycocaEntry> SPtr; 65 /** 66 * A list of shared data pointers for KSycocaEntry. 67 */ 68 typedef QList<SPtr> List; 69 70 public: 71 /** 72 * Construct a dummy servicegroup indexed with @p name. 73 * @param name the name of the service group 74 */ 75 KServiceGroup(const QString &name); 76 77 /** 78 * Construct a service and take all information from a config file 79 * @param _fullpath full path to the config file 80 * @param _relpath relative path to the config file 81 */ 82 KServiceGroup(const QString &_fullpath, const QString &_relpath); 83 84 ~KServiceGroup() override; 85 86 /** 87 * Returns the relative path of the service group. 88 * @return the service group's relative path 89 */ 90 QString relPath() const; 91 92 /** 93 * Returns the caption of this group. 94 * @return the caption of this group 95 */ 96 QString caption() const; 97 98 /** 99 * Returns the name of the icon associated with the group. 100 * @return the name of the icon associated with the group, 101 * or QString() if not set 102 */ 103 QString icon() const; 104 105 /** 106 * Returns the comment about this service group. 107 * @return the descriptive comment for the group, if there is one, 108 * or QString() if not set 109 */ 110 QString comment() const; 111 112 /** 113 * Returns the total number of displayable services in this group and 114 * any of its subgroups. 115 * @return the number of child services 116 */ 117 int childCount() const; 118 119 /** 120 * Returns true if the NoDisplay flag was set, i.e. if this 121 * group should be hidden from menus, while still being in ksycoca. 122 * @return true to hide this service group, false to display it 123 */ 124 bool noDisplay() const; 125 126 /** 127 * Return true if we want to display empty menu entry 128 * @return true to show this service group as menu entry is empty, false to hide it 129 */ 130 bool showEmptyMenu() const; 131 void setShowEmptyMenu(bool b); 132 133 /** 134 * @return true to show an inline header into menu 135 */ 136 bool showInlineHeader() const; 137 void setShowInlineHeader(bool _b); 138 139 /** 140 * @return true to show an inline alias item into menu 141 */ 142 bool inlineAlias() const; 143 void setInlineAlias(bool _b); 144 /** 145 * @return true if we allow to inline menu. 146 */ 147 bool allowInline() const; 148 void setAllowInline(bool _b); 149 150 /** 151 * @return inline limit value 152 */ 153 int inlineValue() const; 154 void setInlineValue(int _val); 155 156 /** 157 * Returns a list of untranslated generic names that should be 158 * be suppressed when showing this group. 159 * E.g. The group "Games/Arcade" might want to suppress the generic name 160 * "Arcade Game" since it's redundant in this particular context. 161 */ 162 QStringList suppressGenericNames() const; 163 164 /** 165 * @internal 166 * Sets information related to the layout of services in this group. 167 */ 168 void setLayoutInfo(const QStringList &layout); 169 170 /** 171 * @internal 172 * Returns information related to the layout of services in this group. 173 */ 174 QStringList layoutInfo() const; 175 176 /** 177 * List of all Services and ServiceGroups within this 178 * ServiceGroup. 179 * @param sorted true to sort items 180 * @param excludeNoDisplay true to exclude items marked "NoDisplay" 181 * @param allowSeparators true to allow separator items to be included 182 * @param sortByGenericName true to sort GenericName+Name instead of Name+GenericName 183 * @return the list of entries 184 */ 185 List entries(bool sorted, bool excludeNoDisplay, bool allowSeparators, bool sortByGenericName = false); 186 List entries(bool sorted, bool excludeNoDisplay); 187 188 /** 189 * List of all Services and ServiceGroups within this 190 * ServiceGroup. 191 * @param sorted true to sort items 192 * @return the list of entried 193 */ 194 List entries(bool sorted = false); 195 196 /** 197 * options for groupEntries and serviceEntries 198 * @see EntriesOptions 199 */ 200 enum EntriesOption { 201 NoOptions = 0x0, /**< no options set */ 202 SortEntries = 0x1, /**< sort items */ 203 ExcludeNoDisplay = 0x2, /**< exclude items marked "NoDisplay" */ 204 AllowSeparators = 0x4, /**< allow separator items to be included */ 205 SortByGenericName = 0x8, /**< sort by GenericName+Name instead of Name+GenericName */ 206 }; 207 /** 208 * Stores a combination of #EntriesOption values. 209 */ 210 Q_DECLARE_FLAGS(EntriesOptions, EntriesOption) 211 212 /** 213 * subgroups for this service group 214 */ 215 QList<Ptr> groupEntries(EntriesOptions options = ExcludeNoDisplay); 216 217 /** 218 * entries of this service group 219 */ 220 KService::List serviceEntries(EntriesOptions options = ExcludeNoDisplay); 221 222 /** 223 * Returns a non-empty string if the group is a special base group. 224 * By default, "Settings/" is the kcontrol base group ("settings") 225 * and "System/Screensavers/" is the screensavers base group ("screensavers"). 226 * This allows moving the groups without breaking those apps. 227 * 228 * The base group is defined by the X-KDE-BaseGroup key 229 * in the .directory file. 230 * @return the base group name, or null if no base group 231 */ 232 QString baseGroupName() const; 233 234 /** 235 * Returns a path to the .directory file describing this service group. 236 * The path is either absolute or relative to the "apps" resource. 237 */ 238 QString directoryEntryPath() const; 239 240 /** 241 * Returns the root service group. 242 * @return the root service group 243 */ 244 static Ptr root(); 245 246 /** 247 * Returns the group with the given relative path. 248 * @param relPath the path of the service group 249 * @return the group with the given relative path name. 250 */ 251 static Ptr group(const QString &relPath); 252 253 /** 254 * Returns the group of services that have X-KDE-ParentApp equal 255 * to @p parent (siblings). 256 * @param parent the name of the service's parent 257 * @return the services group 258 */ 259 static Ptr childGroup(const QString &parent); 260 261 protected: 262 /** 263 * @internal 264 * Add a service to this group 265 */ 266 void addEntry(const KSycocaEntry::Ptr &entry); 267 268 private: 269 friend class KServiceGroupFactory; 270 /** 271 * @internal construct a service from a stream. 272 * The stream must already be positioned at the correct offset 273 */ 274 KServiceGroup(QDataStream &_str, int offset, bool deep); 275 276 Q_DECLARE_PRIVATE(KServiceGroup) 277 }; 278 279 #endif 280