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 kdesktopfile.h <KDesktopFile>
18 *
19 * %KDE Desktop File Management.
20 * This class implements %KDE's support for the freedesktop.org
21 * <em>Desktop Entry Spec</em>.
22 *
23 * @author Pietro Iglio <iglio@kde.org>
24 * @see KConfigBase KConfig
25 * @see <a href="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">Desktop Entry Spec</a>
26 */
27class KCONFIGCORE_EXPORT KDesktopFile : public KConfig
28{
29public:
30 /**
31 * Constructs a KDesktopFile object.
32 *
33 * See QStandardPaths for more information on resources.
34 *
35 * @param resourceType Allows you to change what sort of resource
36 * to search for if @p fileName is not absolute.
37 * For instance, you might want to specify GenericConfigLocation.
38 * @param fileName The name or path of the desktop file. If it
39 * is not absolute, it will be located
40 * using the resource type @p resType.
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 * @param 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 * @param path the path of the file to check
69 * @return true if the file appears to be a desktop file.
70 */
71 static bool isDesktopFile(const QString &path);
72
73 /**
74 * Checks whether the user is authorized to run this desktop file.
75 * By default users are authorized to run all desktop files but
76 * the KIOSK framework can be used to activate certain restrictions.
77 * See README.kiosk for more information.
78 *
79 * Note that desktop files that are not in a standard location (as
80 * specified by XDG_DATA_DIRS) must have their executable bit set
81 * to be authorized, regardless of KIOSK settings, to prevent users
82 * from inadvertently running trojan desktop files.
83 *
84 * @param path the file to check
85 * @return true if the user is authorized to run the file
86 */
87 static bool isAuthorizedDesktopFile(const QString &path);
88
89 /**
90 * Returns the location where changes for the .desktop file @p path
91 * should be written to.
92 */
93 static QString locateLocal(const QString &path);
94
95 /**
96 * Returns the main config group (named "Desktop Entry") in a .desktop file.
97 */
98 KConfigGroup desktopGroup() const;
99
100 /**
101 * Returns the value of the "Type=" entry.
102 * @return the type or QString() if not specified
103 */
104 QString readType() const;
105
106 /**
107 * Returns the value of the "Icon=" entry.
108 * @return the icon or QString() if not specified
109 */
110 QString readIcon() const;
111
112 /**
113 * Returns the value of the "Name=" entry.
114 * @return the name or QString() if not specified
115 */
116 QString readName() const;
117
118 /**
119 * Returns the value of the "Comment=" entry.
120 * @return the comment or QString() if not specified
121 */
122 QString readComment() const;
123
124 /**
125 * Returns the value of the "GenericName=" entry.
126 * @return the generic name or QString() if not specified
127 */
128 QString readGenericName() const;
129
130 /**
131 * Returns the value of the "Path=" entry.
132 * @return the path or QString() if not specified
133 */
134 QString readPath() const;
135
136 /**
137 * Returns the value of the "URL=" entry.
138 * @return the URL or QString() if not specified
139 */
140 QString readUrl() const;
141
142 /**
143 * Returns a list of the "Actions=" entries.
144 * @return the list of actions
145 */
146 QStringList readActions() const;
147
148 /**
149 * Returns a list of the "MimeType=" entries.
150 * @return the list of mime types
151 * @since 5.15
152 */
153 QStringList readMimeTypes() const;
154
155 /**
156 * Sets the desktop action group.
157 * @param group the new action group
158 */
159 KConfigGroup actionGroup(const QString &group);
160 KConfigGroup actionGroup(const QString &group) const;
161
162 /**
163 * Returns true if the action group exists, false otherwise
164 * @param group the action group to test
165 * @return true if the action group exists
166 */
167 bool hasActionGroup(const QString &group) const;
168
169 /**
170 * Checks whether there is a "Type=Link" entry.
171 *
172 * The link points to the "URL=" entry.
173 * @return true if there is a "Type=Link" entry
174 */
175 bool hasLinkType() const;
176
177 /**
178 * Checks whether there is an entry "Type=Application".
179 * @return true if there is a "Type=Application" entry
180 */
181 bool hasApplicationType() const;
182
183 /**
184 * Checks whether there is an entry "Type=FSDevice".
185 * @return true if there is a "Type=FSDevice" entry
186 */
187 bool hasDeviceType() const;
188
189 /**
190 * Checks whether the TryExec field contains a binary
191 * which is found on the local system.
192 * @return true if TryExec contains an existing binary
193 */
194 bool tryExec() const;
195
196 /**
197 * Returns the value of the "X-DocPath=" Or "DocPath=" entry.
198 * @return The value of the "X-DocPath=" Or "DocPath=" entry.
199 */
200 QString readDocPath() const;
201
202 /**
203 * Whether the entry should be suppressed in menus.
204 * This handles the NoDisplay key
205 * @return true to suppress this desktop file
206 * @since 4.1
207 */
208 bool noDisplay() const;
209
210 /**
211 * Copies all entries from this config object to a new
212 * KDesktopFile object that will save itself to @p file.
213 *
214 * Actual saving to @p file happens when the returned object is
215 * destructed or when sync() is called upon it.
216 *
217 * @param file the new KDesktopFile object it will save itself to.
218 */
219 KDesktopFile *copyTo(const QString &file) const;
220
221 /**
222 * Returns the name of the .desktop file that was used to construct this KDesktopFile.
223 */
224 QString fileName() const;
225
226 /**
227 *
228 * @since 6.0
229 */
230 QList<KDesktopFileAction> actions() const;
231
232private:
233 Q_DISABLE_COPY(KDesktopFile)
234
235 Q_DECLARE_PRIVATE(KDesktopFile)
236};
237
238#endif
239

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