KConfig

kdesktopfile.h
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 
12 class KConfigGroup;
13 class KDesktopFileAction;
14 class 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  */
27 class KCONFIGCORE_EXPORT KDesktopFile : public KConfig
28 {
29 public:
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 
232 private:
233  Q_DISABLE_COPY(KDesktopFile)
234 
235  Q_DECLARE_PRIVATE(KDesktopFile)
236 };
237 
238 #endif
KConfig * copyTo(const QString &file, KConfig *config=nullptr) const
Copies all entries from this config object to a new config object that will save itself to file.
Definition: kconfig.cpp:546
The central class of the KDE configuration data system.
Definition: kconfig.h:55
Class for representing an Action of a desktop file.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 04:07:59 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.