1 /* 2 SPDX-FileCopyrightText: 2007-2011 Aaron Seigo <aseigo@kde.org> 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: 356 QExplicitlySharedDataPointer<PackagePrivate> d; 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 370