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

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