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

KDE's Doxygen guidelines are available online.