KPackage::Package
#include <KPackage/Package>
Detailed Description
object representing an installed 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:
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
Constructor & Destructor Documentation
◆ Package() [1/2]
|
explicit |
Default constructor.
- Parameters
-
structure if 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
Definition at line 33 of file package.cpp.
◆ Package() [2/2]
| KPackage::Package::Package | ( | const Package & | other | ) |
Copy constructor.
Definition at line 44 of file package.cpp.
Member Function Documentation
◆ addDirectoryDefinition()
| void KPackage::Package::addDirectoryDefinition | ( | const QByteArray & | key, |
| const QString & | path ) |
Adds a directory to the structure of the package.
It is added as a not-required element with no associated mimeTypes. If an entry with the given key already exists, the path is added to it as a search alternative.
- Parameters
-
key used as an internal label for this directory path the path within the package for this directory
Definition at line 625 of file package.cpp.
◆ addFileDefinition()
| void KPackage::Package::addFileDefinition | ( | const QByteArray & | key, |
| const QString & | path ) |
Adds a file to the structure of the package.
It is added as a not-required element with no associated mimeTypes. If an entry with the given key already exists, the path is added to it as a search alternative.
- Parameters
-
key used as an internal label for this file path the path within the package for this file
Definition at line 645 of file package.cpp.
◆ allowExternalPaths()
| bool KPackage::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 162 of file package.cpp.
◆ contentsPrefixPaths()
| QStringList KPackage::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.
Definition at line 563 of file package.cpp.
◆ cryptographicHash()
| QByteArray KPackage::Package::cryptographicHash | ( | QCryptographicHash::Algorithm | algorithm | ) | const |
- Returns
- a hash digest of the contents of the package in hexadecimal form
- Since
- 5.21
Definition at line 588 of file package.cpp.
◆ defaultPackageRoot()
| QString KPackage::Package::defaultPackageRoot | ( | ) | const |
- Returns
- preferred package root. This defaults to kpackage/generic/
Definition at line 128 of file package.cpp.
◆ directories()
| QList< QByteArray > KPackage::Package::directories | ( | ) | const |
- Returns
- all directories registered as part of this Package's structure
Definition at line 708 of file package.cpp.
◆ entryList()
| QStringList KPackage::Package::entryList | ( | const QByteArray & | key | ) | const |
Get the list of files of a given type.
- Parameters
-
fileType the 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 383 of file package.cpp.
◆ fallbackPackage()
| KPackage::Package KPackage::Package::fallbackPackage | ( | ) | const |
- Returns
- The fallback package root path
Definition at line 153 of file package.cpp.
◆ filePath()
| QString KPackage::Package::filePath | ( | const QByteArray & | 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
-
key the key of the file type to look for, filename optional name of the file to locate within the package
- Returns
- path to the file on disk. QString() if not found.
Definition at line 292 of file package.cpp.
◆ files()
| QList< QByteArray > KPackage::Package::files | ( | ) | const |
- Returns
- all files registered as part of this Package's structure
Definition at line 730 of file package.cpp.
◆ fileUrl()
| QUrl KPackage::Package::fileUrl | ( | const QByteArray & | key, |
| const QString & | filename = QString() ) const |
Get the url to a given file based on the key and an optional filename, is the file:// or qrc:// format 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
-
key the key of the file type to look for, filename optional name of the file to locate within the package
- Returns
- path to the file on disk. QUrl() if not found.
- Since
- 5.41
Definition at line 372 of file package.cpp.
◆ hasValidStructure()
| bool KPackage::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 60 of file package.cpp.
◆ isRequired()
| bool KPackage::Package::isRequired | ( | const QByteArray & | key | ) | const |
- Returns
- true if the item at path exists and is required
Definition at line 104 of file package.cpp.
◆ isValid()
| bool KPackage::Package::isValid | ( | ) | const |
- Returns
- true if all the required components exist
Definition at line 66 of file package.cpp.
◆ metadata()
| KPluginMetaData KPackage::Package::metadata | ( | ) | const |
- Returns
- the package metadata object.
Definition at line 179 of file package.cpp.
◆ mimeTypes()
| QStringList KPackage::Package::mimeTypes | ( | const QByteArray & | key | ) | const |
- Returns
- the mimeTypes associated with the path, if any
Definition at line 114 of file package.cpp.
◆ operator=()
Assignment operator.
Definition at line 51 of file package.cpp.
◆ path()
| const QString KPackage::Package::path | ( | ) | const |
- Returns
- the path to the root of this particular package
Definition at line 558 of file package.cpp.
◆ removeDefinition()
| void KPackage::Package::removeDefinition | ( | const QByteArray & | key | ) |
Removes a definition from the structure of the package.
- Parameters
-
key the internal label of the file or directory to remove
Definition at line 665 of file package.cpp.
◆ requiredDirectories()
| QList< QByteArray > KPackage::Package::requiredDirectories | ( | ) | const |
- Returns
- all directories registered as part of this Package's required structure
Definition at line 719 of file package.cpp.
◆ requiredFiles()
| QList< QByteArray > KPackage::Package::requiredFiles | ( | ) | const |
- Returns
- all files registered as part of this Package's required structure
Definition at line 741 of file package.cpp.
◆ setAllowExternalPaths()
| void KPackage::Package::setAllowExternalPaths | ( | bool | allow | ) |
Sets whether or not external paths/symlinks can be followed by a package.
- Parameters
-
allow true if paths/symlinks outside of the package should be followed, false if they should be rejected.
Definition at line 173 of file package.cpp.
◆ setContentsPrefixPaths()
| void KPackage::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
-
prefix paths the directory prefix to use
Definition at line 568 of file package.cpp.
◆ setDefaultMimeTypes()
| void KPackage::Package::setDefaultMimeTypes | ( | const 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
-
mimeTypes a list of mimeTypes
Definition at line 692 of file package.cpp.
◆ setDefaultPackageRoot()
| void KPackage::Package::setDefaultPackageRoot | ( | const QString & | packageRoot | ) |
Sets preferred package root.
Definition at line 133 of file package.cpp.
◆ setFallbackPackage()
| void KPackage::Package::setFallbackPackage | ( | const KPackage::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
-
path package root path
- See also
- setPath
Definition at line 142 of file package.cpp.
◆ setMetadata()
| void KPackage::Package::setMetadata | ( | const KPluginMetaData & | data | ) |
Sets the metadata for the KPackage.
This overwrites the current metadata. This should be used in case a kpackage gets loaded by name, based on the path a C++ plugin which has embedded metadata.
- Since
- 5.88
Definition at line 167 of file package.cpp.
◆ setMimeTypes()
| void KPackage::Package::setMimeTypes | ( | const QByteArray & | key, |
| const QStringList & | mimeTypes ) |
Define mimeTypes for a given part of the structure The path must already have been added using addDirectoryDefinition or addFileDefinition.
- Parameters
-
key the entry within the package mimeTypes a list of mimeTypes
Definition at line 698 of file package.cpp.
◆ setPath()
| void KPackage::Package::setPath | ( | const QString & | path | ) |
Sets the path to the root of this package.
- Parameters
-
path an absolute path, or a relative path to the default package root
Definition at line 439 of file package.cpp.
◆ setRequired()
| void KPackage::Package::setRequired | ( | const QByteArray & | 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
-
key the entry within the package required true if this entry is required, false if not
Definition at line 678 of file package.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:16:48 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.