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
14class KBuildServiceGroupFactory;
15
16class 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 */
52class KSERVICE_EXPORT KServiceGroup : public KSycocaEntry
53{
54 friend class KBuildServiceGroupFactory;
55
56public:
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
70public:
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
261protected:
262 /**
263 * @internal
264 * Add a service to this group
265 */
266 void addEntry(const KSycocaEntry::Ptr &entry);
267
268private:
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 KSERVICE_NO_EXPORT KServiceGroup(QDataStream &_str, int offset, bool deep);
275
276 Q_DECLARE_PRIVATE(KServiceGroup)
277};
278
279#endif
280

source code of kservice/src/services/kservicegroup.h