Plasma::Package

Plasma::Package Class Reference

#include <Plasma/Package>

Public Member Functions

 Package (PackageStructure *structure=nullptr)
 
 Package (const KPackage::Package &other)
 
 Package (const Package &other)
 
void addDirectoryDefinition (const char *key, const QString &path, const QString &name)
 
void addFileDefinition (const char *key, const QString &path, const QString &name)
 
bool allowExternalPaths () const
 
QString contentsHash () const
 
QStringList contentsPrefixPaths () const
 
QString defaultPackageRoot () const
 
QList< const char * > directories () const
 
QStringList entryList (const char *key) const
 
Plasma::Package fallbackPackage () const
 
QString filePath (const char *key, const QString &filename=QString()) const
 
QList< const char * > files () const
 
bool hasValidStructure () const
 
KJobinstall (const QString &sourcePackage, const QString &packageRoot=QString())
 
bool isRequired (const char *key) const
 
bool isValid () const
 
KPackage::Package kPackage () const
 
KPluginInfo metadata () const
 
QStringList mimeTypes (const char *key) const
 
QString name (const char *key) const
 
Packageoperator= (const Package &rhs)
 
const QString path () const
 
void removeDefinition (const char *key)
 
QList< const char * > requiredDirectories () const
 
QList< const char * > requiredFiles () const
 
QString servicePrefix () const
 
void setAllowExternalPaths (bool allow)
 
void setContentsPrefixPaths (const QStringList &prefixPaths)
 
void setDefaultMimeTypes (QStringList mimeTypes)
 
void setDefaultPackageRoot (const QString &packageRoot)
 
void setFallbackPackage (const Plasma::Package &package)
 
void setMimeTypes (const char *key, QStringList mimeTypes)
 
void setPath (const QString &path)
 
void setRequired (const char *key, bool required)
 
void setServicePrefix (const QString &servicePrefix)
 
KJobuninstall (const QString &packageName, const QString &packageRoot)
 

Detailed Description

object representing an installed Plasma package

Package defines what is in a package and provides easy access to the contents.

To define a package, one might write the following code:

Package package;
package.addDirectoryDefinition("images", "pics/", i18n("Images"));
mimeTypes << "image/svg" << "image/png" << "image/jpeg";
package.setMimeTypes("images", mimeTypes);
package.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
mimeTypes.clear();
mimeTypes << "text/\*";
package.setMimeTypes("scripts", mimeTypes);
package.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
package.setRequired("mainscript", true);

One may also choose to create a subclass of PackageStructure and include the setup in the constructor.

Either way, Package creates a self-documenting contract between the packager and the application without exposing package internals such as actual on-disk structure of the package or requiring that all contents be explicitly known ahead of time.

Subclassing PackageStructure does have provide a number of potential const benefits:

  • the package can be notified of path changes via the virtual pathChanged() method
  • the subclass may implement mechanisms to install and remove packages using the virtual install and uninstall methods
  • subclasses can be compiled as plugins for easy re-use
Deprecated:
Since 5.6, use KPackage::Package instead

Definition at line 74 of file package.h.

Constructor & Destructor Documentation

Plasma::Package::Package ( PackageStructure *  structure = nullptr)
explicit

Default constructor.

Parameters
structureif a NULL pointer is passed in, this will creates an empty (invalid) Package; otherwise the structure is allowed to set up the Package's initial layout
Since
4.6

Definition at line 47 of file package.cpp.

Plasma::Package::Package ( const KPackage::Package other)

Copy constructore.

Since
4.6

Definition at line 74 of file package.cpp.

Plasma::Package::Package ( const Package other)

Copy constructore.

Since
4.6

Definition at line 66 of file package.cpp.

Member Function Documentation

void Plasma::Package::addDirectoryDefinition ( const char *  key,
const QString path,
const QString name 
)

Adds a directory to the structure of the package.

It is added as a not-required element with no associated mimeTypes.

Starting in 4.6, if an entry with the given key already exists, the path is added to it as a search alternative.

Parameters
keyused as an internal label for this directory
paththe path within the package for this directory
namethe user visible (translated) name for the directory

Definition at line 217 of file package.cpp.

void Plasma::Package::addFileDefinition ( const char *  key,
const QString path,
const QString name 
)

Adds a file to the structure of the package.

It is added as a not-required element with no associated mimeTypes.

Starting in 4.6, if an entry with the given key already exists, the path is added to it as a search alternative.

Parameters
keyused as an internal label for this file
paththe path within the package for this file
namethe user visible (translated) name for the file

Definition at line 222 of file package.cpp.

bool Plasma::Package::allowExternalPaths ( ) const
Returns
true if paths/symlinks outside the package itself should be followed. By default this is set to false for security reasons.

Definition at line 163 of file package.cpp.

QString Plasma::Package::contentsHash ( ) const
Returns
a SHA1 hash digest of the contents of the package in hexadecimal form
Since
4.4

Definition at line 212 of file package.cpp.

QStringList Plasma::Package::contentsPrefixPaths ( ) const
Returns
the prefix paths inserted between the base path and content entries, in order of priority. When searching for a file, all paths will be tried in order.
Since
4.6

Definition at line 202 of file package.cpp.

QString Plasma::Package::defaultPackageRoot ( ) const
Returns
preferred package root. This defaults to plasma/plasmoids/

Definition at line 123 of file package.cpp.

QList< const char * > Plasma::Package::directories ( ) const
Returns
all directories registered as part of this Package's structure

Definition at line 247 of file package.cpp.

QStringList Plasma::Package::entryList ( const char *  key) const

Get the list of files of a given type.

Parameters
fileTypethe type of file to look for, as defined in the package structure.
Returns
list of files by name, suitable for passing to filePath

Definition at line 183 of file package.cpp.

Plasma::Package Plasma::Package::fallbackPackage ( ) const
Returns
The fallback package root path

Definition at line 139 of file package.cpp.

QString Plasma::Package::filePath ( const char *  key,
const QString filename = QString() 
) const

Get the path to a given file based on the key and an optional filename.

Example: finding the main script in a scripting package: filePath("mainscript")

Example: finding a specific image in the images directory: filePath("images", "myimage.png")

Parameters
keythe key of the file type to look for,
filenameoptional name of the file to locate within the package
Returns
path to the file on disk. QString() if not found.

Definition at line 178 of file package.cpp.

QList< const char * > Plasma::Package::files ( ) const
Returns
all files registered as part of this Package's structure

Definition at line 269 of file package.cpp.

bool Plasma::Package::hasValidStructure ( ) const
Returns
true if this package has a valid PackageStructure associatedw it with it. A package may not be valid, but have a valid structure. Useful when dealing with Package objects in a semi-initialized state (e.g. before calling setPath())
Since
5.1

Definition at line 98 of file package.cpp.

KJob * Plasma::Package::install ( const QString sourcePackage,
const QString packageRoot = QString() 
)

Installs a package matching this package structure.

By default installs a native Plasma::Package.

Returns
KJob to track installation progress and result

Definition at line 291 of file package.cpp.

bool Plasma::Package::isRequired ( const char *  key) const
Returns
true if the item at path exists and is required

Definition at line 113 of file package.cpp.

bool Plasma::Package::isValid ( ) const
Returns
true if all the required components exist

Definition at line 103 of file package.cpp.

KPackage::Package Plasma::Package::kPackage ( ) const
Returns
the wrapped KPackage::Package instance, which deprecated this class
Since
5.28

Definition at line 158 of file package.cpp.

KPluginInfo Plasma::Package::metadata ( ) const
Returns
the package metadata object.

Definition at line 173 of file package.cpp.

QStringList Plasma::Package::mimeTypes ( const char *  key) const
Returns
the mimeTypes associated with the path, if any

Definition at line 118 of file package.cpp.

QString Plasma::Package::name ( const char *  key) const
Returns
user visible name for the given entry

Definition at line 108 of file package.cpp.

Package & Plasma::Package::operator= ( const Package rhs)

Assignment operator.

Since
4.6

Definition at line 87 of file package.cpp.

const QString Plasma::Package::path ( ) const
Returns
the path to the root of this particular package

Definition at line 197 of file package.cpp.

void Plasma::Package::removeDefinition ( const char *  key)

Removes a definition from the structure of the package.

Since
4.6
Parameters
keythe internal label of the file or directory to remove

Definition at line 227 of file package.cpp.

QList< const char * > Plasma::Package::requiredDirectories ( ) const
Returns
all directories registered as part of this Package's required structure

Definition at line 258 of file package.cpp.

QList< const char * > Plasma::Package::requiredFiles ( ) const
Returns
all files registered as part of this Package's required structure

Definition at line 280 of file package.cpp.

QString Plasma::Package::servicePrefix ( ) const
Returns
service prefix used in desktop files. This defaults to plasma-applet-

Definition at line 148 of file package.cpp.

void Plasma::Package::setAllowExternalPaths ( bool  allow)

Sets whether or not external paths/symlinks can be followed by a package.

Parameters
allowtrue if paths/symlinks outside of the package should be followed, false if they should be rejected.

Definition at line 168 of file package.cpp.

void Plasma::Package::setContentsPrefixPaths ( const QStringList prefixPaths)

Sets the prefixes that all the contents in this package should appear under.

This defaults to "contents/" and is added automatically between the base path and the entries as defined by the package structure. Multiple entries can be added. In this case each file request will be searched in all prefixes in order, and the first found will be returned.

Parameters
prefixpaths the directory prefix to use
Since
4.6

Definition at line 207 of file package.cpp.

void Plasma::Package::setDefaultMimeTypes ( QStringList  mimeTypes)

Defines the default mimeTypes for any definitions that do not have associated mimeTypes.

Handy for packages with only one or predominantly one file type.

Parameters
mimeTypesa list of mimeTypes

Definition at line 237 of file package.cpp.

void Plasma::Package::setDefaultPackageRoot ( const QString packageRoot)

Sets preferred package root.

Definition at line 128 of file package.cpp.

void Plasma::Package::setFallbackPackage ( const Plasma::Package package)

Sets the fallback package root path If a file won't be found in this package, it will search it in the package with the same structure identified by path It is intended to be used by the packageStructure.

Parameters
pathpackage root path
See also
setPath

Definition at line 133 of file package.cpp.

void Plasma::Package::setMimeTypes ( const char *  key,
QStringList  mimeTypes 
)

Define mimeTypes for a given part of the structure The path must already have been added using addDirectoryDefinition or addFileDefinition.

Parameters
keythe entry within the package
mimeTypesa list of mimeTypes

Definition at line 242 of file package.cpp.

void Plasma::Package::setPath ( const QString path)

Sets the path to the root of this package.

Parameters
pathan absolute path, or a relative path to the default package root
Since
4.3

Definition at line 188 of file package.cpp.

void Plasma::Package::setRequired ( const char *  key,
bool  required 
)

Sets whether or not a given part of the structure is required or not.

The path must already have been added using addDirectoryDefinition or addFileDefinition.

Parameters
keythe entry within the package
requiredtrue if this entry is required, false if not

Definition at line 232 of file package.cpp.

void Plasma::Package::setServicePrefix ( const QString servicePrefix)

Sets service prefix.

Definition at line 153 of file package.cpp.

KJob * Plasma::Package::uninstall ( const QString packageName,
const QString packageRoot 
)

Uninstalls a package matching this package structure.

Returns
KJob to track removal progress and result

Definition at line 301 of file package.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Fri Sep 25 2020 22:41:40 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.