1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Pietro Iglio <iglio@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7#ifndef KDESKTOPFILE_H
8#define KDESKTOPFILE_H
9
10#include <kconfig.h>
11
12class KConfigGroup;
13class KDesktopFileAction;
14class KDesktopFilePrivate;
15
16/*!
17 * \class KDesktopFile
18 * \inmodule KConfigGui
19 *
20 * This class implements KDE's support for the freedesktop.org
21 * \l {https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html} {Desktop Entry Spec}.
22 *
23 * \sa KConfigBase
24 * \sa KConfig
25 */
26class KCONFIGCORE_EXPORT KDesktopFile : public KConfig
27{
28public:
29 /*!
30 * Constructs a KDesktopFile object.
31 *
32 * See QStandardPaths for more information on resources.
33 *
34 * \a resourceType Allows you to change what sort of resource
35 * to search for if \a fileName is not absolute.
36 * For instance, you might want to specify GenericConfigLocation.
37 *
38 * \a fileName The name or path of the desktop file. If it
39 * is not absolute, it will be located
40 * using the resource type \a resourceType.
41 */
42 explicit KDesktopFile(QStandardPaths::StandardLocation resourceType, const QString &fileName);
43
44 /*!
45 * Constructs a KDesktopFile object.
46 *
47 * See QStandardPaths for more information on resources.
48 *
49 * \a fileName The name or path of the desktop file. If it
50 * is not absolute, it will be located
51 * using the resource type ApplicationsLocation
52 */
53 explicit KDesktopFile(const QString &fileName);
54
55 /*!
56 * Destructs the KDesktopFile object.
57 *
58 * Writes back any changed configuration entries.
59 */
60 ~KDesktopFile() override;
61
62 /*!
63 * Checks whether this is really a desktop file.
64 *
65 * The check is performed looking at the file extension (the file is not
66 * opened).
67 * Currently, the only valid extension is ".desktop".
68 *
69 * \a path the path of the file to check
70 *
71 * Returns \c true if the file appears to be a desktop file.
72 */
73 static bool isDesktopFile(const QString &path);
74
75 /*!
76 * Checks whether the user is authorized to run this desktop file.
77 * By default users are authorized to run all desktop files but
78 * the KIOSK framework can be used to activate certain restrictions.
79 * See README.kiosk for more information.
80 *
81 * Note that desktop files that are not in a standard location (as
82 * specified by XDG_DATA_DIRS) must have their executable bit set
83 * to be authorized, regardless of KIOSK settings, to prevent users
84 * from inadvertently running trojan desktop files.
85 *
86 * \a path the file to check
87 *
88 * Returns \c true if the user is authorized to run the file
89 */
90 static bool isAuthorizedDesktopFile(const QString &path);
91
92 /*!
93 * Returns the location where changes for the .desktop file \a path
94 * should be written to.
95 */
96 static QString locateLocal(const QString &path);
97
98 /*!
99 * Returns the main config group (named "Desktop Entry") in a .desktop file.
100 */
101 KConfigGroup desktopGroup() const;
102
103 /*!
104 * Returns the value of the "Type=" entry, or QString() if not specified
105 */
106 QString readType() const;
107
108 /*!
109 * Returns the value of the "Icon=" entry, or QString() if not specified
110 */
111 QString readIcon() const;
112
113 /*!
114 * Returns the value of the "Name=" entry, or QString() if not specified
115 */
116 QString readName() const;
117
118 /*!
119 * Returns the value of the "Comment=" entry, or QString() if not specified
120 */
121 QString readComment() const;
122
123 /*!
124 * Returns the value of the "GenericName=" entry, or QString() if not specified
125 */
126 QString readGenericName() const;
127
128 /*!
129 * Returns the value of the "Path=" entry, or QString() if not specified
130 */
131 QString readPath() const;
132
133 /*!
134 * Returns the value of the "URL=" entry, or QString() if not specified
135 */
136 QString readUrl() const;
137
138 /*!
139 * Returns a list of the "Actions=" entries
140 */
141 QStringList readActions() const;
142
143 /*!
144 * Returns a list of the "MimeType=" entries
145 * \since 5.15
146 */
147 QStringList readMimeTypes() const;
148
149 /*!
150 * Sets the desktop action group.
151 *
152 * \a group the new action group
153 */
154 KConfigGroup actionGroup(const QString &group);
155
156 /*!
157 * Sets the desktop action group.
158 *
159 * \a group the new action group
160 */
161 KConfigGroup actionGroup(const QString &group) const;
162
163 /*!
164 * Returns \c true if the action group exists, \c false otherwise
165 *
166 * \a group the action group to test
167 */
168 bool hasActionGroup(const QString &group) const;
169
170 /*!
171 * Checks whether there is a "Type=Link" entry.
172 *
173 * The link points to the "URL=" entry.
174 */
175 bool hasLinkType() const;
176
177 /*!
178 * Checks whether there is an entry "Type=Application".
179 */
180 bool hasApplicationType() const;
181
182 /*!
183 * Checks whether there is an entry "Type=FSDevice".
184 */
185 bool hasDeviceType() const;
186
187 /*!
188 * Checks whether the TryExec field contains a binary
189 * which is found on the local system.
190 */
191 bool tryExec() const;
192
193 /*!
194 * Returns the value of the "X-DocPath=" Or "DocPath=" entry.
195 */
196 QString readDocPath() const;
197
198 /*!
199 * Whether the entry should be suppressed in menus.
200 *
201 * This handles the NoDisplay key
202 * \since 4.1
203 */
204 bool noDisplay() const;
205
206 /*!
207 * Copies all entries from this config object to a new
208 * KDesktopFile object that will save itself to \a file.
209 *
210 * Actual saving to \a file happens when the returned object is
211 * destructed or when sync() is called upon it.
212 *
213 * \a file the new KDesktopFile object it will save itself to.
214 */
215 KDesktopFile *copyTo(const QString &file) const;
216
217 /*!
218 * Returns the name of the .desktop file that was used to construct this KDesktopFile.
219 */
220 QString fileName() const;
221
222 /*!
223 * Returns the desktop file's actions
224 *
225 * \since 6.0
226 */
227 QList<KDesktopFileAction> actions() const;
228
229private:
230 Q_DISABLE_COPY(KDesktopFile)
231
232 Q_DECLARE_PRIVATE(KDesktopFile)
233};
234
235#endif
236

source code of kconfig/src/core/kdesktopfile.h