Plasma

package.h
1 /*
2  SPDX-FileCopyrightText: 2007-2011 Aaron Seigo <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef PLASMA_PACKAGE_H
8 #define PLASMA_PACKAGE_H
9 
10 #include <QStringList>
11 
12 #include <plasma/plasma.h>
13 #include <plasma/plasma_export.h>
14 
15 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 94)
16 #include <KPluginInfo>
17 #endif
18 
19 class KJob;
20 
21 // not 5.6, as last Plasma API using this class only got removed later
22 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 28)
23 
24 namespace KPackage
25 {
26 class Package;
27 }
28 
29 namespace Plasma
30 {
31 /**
32  * @class Package plasma/package.h <Plasma/Package>
33  *
34  * @short object representing an installed Plasma package
35  *
36  * Package defines what is in a package and provides easy access to the contents.
37  *
38  * To define a package, one might write the following code:
39  *
40  @code
41  Package package;
42 
43  package.addDirectoryDefinition("images", "pics/", i18n("Images"));
44  QStringList mimeTypes;
45  mimeTypes << "image/svg" << "image/png" << "image/jpeg";
46  package.setMimeTypes("images", mimeTypes);
47 
48  package.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
49  mimeTypes.clear();
50  mimeTypes << "text/\*";
51  package.setMimeTypes("scripts", mimeTypes);
52 
53  package.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
54  package.setRequired("mainscript", true);
55  @endcode
56  * One may also choose to create a subclass of PackageStructure and include the setup
57  * in the constructor.
58  *
59  * Either way, Package creates a self-documenting contract between the packager and
60  * the application without exposing package internals such as actual on-disk structure
61  * of the package or requiring that all contents be explicitly known ahead of time.
62  *
63  * Subclassing PackageStructure does have provide a number of potential const benefits:
64  * * the package can be notified of path changes via the virtual pathChanged() method
65  * * the subclass may implement mechanisms to install and remove packages using the
66  * virtual install and uninstall methods
67  * * subclasses can be compiled as plugins for easy re-use
68  *
69  * @deprecated Since 5.6, use KPackage::Package instead
70  **/
71 // TODO: write documentation on USING a package
72 
73 class PackagePrivate;
74 class PackageStructure;
75 
76 class PLASMA_EXPORT Package
77 {
78 public:
79  /**
80  * Default constructor
81  *
82  * @param structure if a NULL pointer is passed in, this will creates an empty (invalid) Package;
83  * otherwise the structure is allowed to set up the Package's initial layout
84  * @since 4.6
85  */
86  PLASMA_DEPRECATED_VERSION(5, 6, "Use KPackage API")
87  explicit Package(PackageStructure *structure = nullptr);
88 
89  /**
90  * Copy constructore
91  * @since 4.6
92  */
93  PLASMA_DEPRECATED_VERSION(5, 6, "Use KPackage API")
94  Package(const KPackage::Package &other);
95 
96  /**
97  * Copy constructore
98  * @since 4.6
99  */
100  PLASMA_DEPRECATED_VERSION(5, 6, "Use KPackage API")
101  Package(const Package &other);
102 
103  ~Package();
104 
105  /**
106  * Assignment operator
107  * @since 4.6
108  */
109  Package &operator=(const Package &rhs);
110 
111  /**
112  * @return true if this package has a valid PackageStructure associatedw it with it.
113  * A package may not be valid, but have a valid structure. Useful when dealing with
114  * Package objects in a semi-initialized state (e.g. before calling setPath())
115  * @since 5.1
116  */
117  bool hasValidStructure() const;
118 
119  /**
120  * @return true if all the required components exist
121  **/
122  bool isValid() const;
123 
124  /**
125  * Sets the path to the root of this package
126  * @param path an absolute path, or a relative path to the default package root
127  * @since 4.3
128  */
129  void setPath(const QString &path);
130 
131  /**
132  * @return the path to the root of this particular package
133  */
134  const QString path() const;
135 
136  /**
137  * Get the path to a given file based on the key and an optional filename.
138  * Example: finding the main script in a scripting package:
139  * filePath("mainscript")
140  *
141  * Example: finding a specific image in the images directory:
142  * filePath("images", "myimage.png")
143  *
144  * @param key the key of the file type to look for,
145  * @param filename optional name of the file to locate within the package
146  * @return path to the file on disk. QString() if not found.
147  **/
148  QString filePath(const char *key, const QString &filename = QString()) const;
149 
150  /**
151  * Get the list of files of a given type.
152  *
153  * @param fileType the type of file to look for, as defined in the
154  * package structure.
155  * @return list of files by name, suitable for passing to filePath
156  **/
157  QStringList entryList(const char *key) const;
158 
159  /**
160  * @return user visible name for the given entry
161  **/
162  QString name(const char *key) const;
163 
164  /**
165  * @return true if the item at path exists and is required
166  **/
167  bool isRequired(const char *key) const;
168 
169  /**
170  * @return the mimeTypes associated with the path, if any
171  **/
172  QStringList mimeTypes(const char *key) const;
173 
174  /**
175  * @return the prefix paths inserted between the base path and content entries, in order of priority.
176  * When searching for a file, all paths will be tried in order.
177  * @since 4.6
178  */
179  QStringList contentsPrefixPaths() const;
180 
181  /**
182  * @return preferred package root. This defaults to plasma/plasmoids/
183  */
184  QString defaultPackageRoot() const;
185 
186  /**
187  * @return service prefix used in desktop files. This defaults to plasma-applet-
188  */
189  QString servicePrefix() const;
190 
191  /**
192  * @return true if paths/symlinks outside the package itself should be followed.
193  * By default this is set to false for security reasons.
194  */
195  bool allowExternalPaths() const;
196 
197  /**
198  * @return the package metadata object.
199  */
200  KPluginInfo metadata() const;
201 
202  /**
203  * @return a SHA1 hash digest of the contents of the package in hexadecimal form
204  * @since 4.4
205  */
206  QString contentsHash() const;
207 
208  /**
209  * Adds a directory to the structure of the package. It is added as
210  * a not-required element with no associated mimeTypes.
211  *
212  * Starting in 4.6, if an entry with the given key
213  * already exists, the path is added to it as a search alternative.
214  *
215  * @param key used as an internal label for this directory
216  * @param path the path within the package for this directory
217  * @param name the user visible (translated) name for the directory
218  **/
219  void addDirectoryDefinition(const char *key, const QString &path, const QString &name);
220 
221  /**
222  * Adds a file to the structure of the package. It is added as
223  * a not-required element with no associated mimeTypes.
224  *
225  * Starting in 4.6, if an entry with the given key
226  * already exists, the path is added to it as a search alternative.
227  *
228  * @param key used as an internal label for this file
229  * @param path the path within the package for this file
230  * @param name the user visible (translated) name for the file
231  **/
232  void addFileDefinition(const char *key, const QString &path, const QString &name);
233 
234  /**
235  * Removes a definition from the structure of the package.
236  * @since 4.6
237  * @param key the internal label of the file or directory to remove
238  */
239  void removeDefinition(const char *key);
240 
241  /**
242  * Sets whether or not a given part of the structure is required or not.
243  * The path must already have been added using addDirectoryDefinition
244  * or addFileDefinition.
245  *
246  * @param key the entry within the package
247  * @param required true if this entry is required, false if not
248  */
249  void setRequired(const char *key, bool required);
250 
251  /**
252  * Defines the default mimeTypes for any definitions that do not have
253  * associated mimeTypes. Handy for packages with only one or predominantly
254  * one file type.
255  *
256  * @param mimeTypes a list of mimeTypes
257  **/
258  void setDefaultMimeTypes(QStringList mimeTypes);
259 
260  /**
261  * Define mimeTypes for a given part of the structure
262  * The path must already have been added using addDirectoryDefinition
263  * or addFileDefinition.
264  *
265  * @param key the entry within the package
266  * @param mimeTypes a list of mimeTypes
267  **/
268  void setMimeTypes(const char *key, QStringList mimeTypes);
269 
270  /**
271  * Sets the prefixes that all the contents in this package should
272  * appear under. This defaults to "contents/" and is added automatically
273  * between the base path and the entries as defined by the package
274  * structure. Multiple entries can be added.
275  * In this case each file request will be searched in all prefixes in order,
276  * and the first found will be returned.
277  *
278  * @param prefix paths the directory prefix to use
279  * @since 4.6
280  */
281  void setContentsPrefixPaths(const QStringList &prefixPaths);
282 
283  /**
284  * Sets service prefix.
285  */
286  void setServicePrefix(const QString &servicePrefix);
287 
288  /**
289  * Sets whether or not external paths/symlinks can be followed by a package
290  * @param allow true if paths/symlinks outside of the package should be followed,
291  * false if they should be rejected.
292  */
293  void setAllowExternalPaths(bool allow);
294 
295  /**
296  * Sets preferred package root.
297  */
298  void setDefaultPackageRoot(const QString &packageRoot);
299 
300  /**
301  * Sets the fallback package root path
302  * If a file won't be found in this package, it will search it in the package
303  * with the same structure identified by path
304  * It is intended to be used by the packageStructure
305  * @param path package root path @see setPath
306  */
307  void setFallbackPackage(const Plasma::Package &package);
308 
309  /**
310  * @return The fallback package root path
311  */
312  Plasma::Package fallbackPackage() const;
313 
314  // Content structure description methods
315  /**
316  * @return all directories registered as part of this Package's structure
317  */
318  QList<const char *> directories() const;
319 
320  /**
321  * @return all directories registered as part of this Package's required structure
322  */
323  QList<const char *> requiredDirectories() const;
324 
325  /**
326  * @return all files registered as part of this Package's structure
327  */
328  QList<const char *> files() const;
329 
330  /**
331  * @return all files registered as part of this Package's required structure
332  */
333  QList<const char *> requiredFiles() const;
334 
335  /**
336  * Installs a package matching this package structure. By default installs a
337  * native Plasma::Package.
338  *
339  * @return KJob to track installation progress and result
340  **/
341  KJob *install(const QString &sourcePackage, const QString &packageRoot = QString());
342 
343  /**
344  * Uninstalls a package matching this package structure.
345  *
346  * @return KJob to track removal progress and result
347  */
348  KJob *uninstall(const QString &packageName, const QString &packageRoot);
349 
350  /**
351  * @returns the wrapped KPackage::Package instance, which deprecated this class
352  *
353  * @since 5.28
354  */
355  KPackage::Package kPackage() const;
356 
357 private:
359  friend class PackagePrivate;
360  friend class PackageStructure;
361  friend class AppletPrivate;
362  friend class Applet;
363  friend class Corona;
364 };
365 
366 }
367 Q_DECLARE_METATYPE(Plasma::Package)
368 
369 #endif // PLASMA_ENABLE_DEPRECATED_SINCE(5, 28)
370 
371 #endif
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
A bookkeeping Scene for Plasma::Applets.
Definition: corona.h:27
object representing an installed Plasma package
Definition: package.h:76
The base Applet class.
Definition: applet.h:71
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:13:44 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.