Plasma::Package Class Reference

#include <Plasma/Package>

Public Member Functions
	Package (const KPackage::Package &other)
	Package (const Package &other)
	Package (PackageStructure *structure=nullptr)
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
KJob *	install (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
Package &	operator= (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)
KJob *	uninstall (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"));
QStringList mimeTypes;
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 76 of file package.h.

Constructor & Destructor Documentation

Package() [1/3]

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

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

Since

4.6

Definition at line 44 of file package.cpp.

Package() [2/3]

Plasma::Package::Package

(

const KPackage::Package &

other

)

Copy constructore.

Since

4.6

Definition at line 71 of file package.cpp.

Package() [3/3]

Plasma::Package::Package

(

const Package &

other

)

Copy constructore.

Since

4.6

Definition at line 63 of file package.cpp.

Member Function Documentation

addDirectoryDefinition()

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

key	used as an internal label for this directory
path	the path within the package for this directory
name	the user visible (translated) name for the directory

Definition at line 214 of file package.cpp.

addFileDefinition()

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

key	used as an internal label for this file
path	the path within the package for this file
name	the user visible (translated) name for the file

Definition at line 219 of file package.cpp.

allowExternalPaths()

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 160 of file package.cpp.

contentsHash()

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 209 of file package.cpp.

contentsPrefixPaths()

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 199 of file package.cpp.

defaultPackageRoot()

QString Plasma::Package::defaultPackageRoot

(

)

const

Returns

preferred package root. This defaults to plasma/plasmoids/

Definition at line 120 of file package.cpp.

directories()

QList< const char * > Plasma::Package::directories

(

)

const

Returns

all directories registered as part of this Package's structure

Definition at line 244 of file package.cpp.

entryList()

QStringList Plasma::Package::entryList

(

const char *

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 180 of file package.cpp.

fallbackPackage()

Plasma::Package Plasma::Package::fallbackPackage

(

)

const

Returns

The fallback package root path

Definition at line 136 of file package.cpp.

filePath()

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

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 175 of file package.cpp.

files()

QList< const char * > Plasma::Package::files

(

)

const

Returns

all files registered as part of this Package's structure

Definition at line 266 of file package.cpp.

hasValidStructure()

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 95 of file package.cpp.

install()

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 288 of file package.cpp.

isRequired()

bool Plasma::Package::isRequired

(

const char *

key

)

const

Returns

true if the item at path exists and is required

Definition at line 110 of file package.cpp.

isValid()

bool Plasma::Package::isValid

(

)

const

Returns

true if all the required components exist

Definition at line 100 of file package.cpp.

kPackage()

KPackage::Package Plasma::Package::kPackage

(

)

const

Returns

the wrapped KPackage::Package instance, which deprecated this class

Since

5.28

Definition at line 155 of file package.cpp.

metadata()

KPluginInfo Plasma::Package::metadata

(

)

const

Returns

the package metadata object.

Definition at line 170 of file package.cpp.

mimeTypes()

QStringList Plasma::Package::mimeTypes

(

const char *

key

)

const

Returns

the mimeTypes associated with the path, if any

Definition at line 115 of file package.cpp.

name()

QString Plasma::Package::name

(

const char *

key

)

const

Returns

user visible name for the given entry

Definition at line 105 of file package.cpp.

operator=()

Package & Plasma::Package::operator=

(

const Package &

rhs

)

Assignment operator.

Since

4.6

Definition at line 84 of file package.cpp.

path()

const QString Plasma::Package::path

(

)

const

Returns

the path to the root of this particular package

Definition at line 194 of file package.cpp.

removeDefinition()

void Plasma::Package::removeDefinition

(

const char *

key

)

Removes a definition from the structure of the package.

Since

4.6

Parameters

key	the internal label of the file or directory to remove

Definition at line 224 of file package.cpp.

requiredDirectories()

QList< const char * > Plasma::Package::requiredDirectories

(

)

const

Returns

all directories registered as part of this Package's required structure

Definition at line 255 of file package.cpp.

requiredFiles()

QList< const char * > Plasma::Package::requiredFiles

(

)

const

Returns

all files registered as part of this Package's required structure

Definition at line 277 of file package.cpp.

servicePrefix()

QString Plasma::Package::servicePrefix

(

)

const

Returns

service prefix used in desktop files. This defaults to plasma-applet-

Definition at line 145 of file package.cpp.

setAllowExternalPaths()

void Plasma::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 165 of file package.cpp.

setContentsPrefixPaths()

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

prefix

paths the directory prefix to use

Since

4.6

Definition at line 204 of file package.cpp.

setDefaultMimeTypes()

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

mimeTypes

a list of mimeTypes

Definition at line 234 of file package.cpp.

setDefaultPackageRoot()

void Plasma::Package::setDefaultPackageRoot

(

const QString &

packageRoot

)

Sets preferred package root.

Definition at line 125 of file package.cpp.

setFallbackPackage()

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

path	package root path

See also

setPath

Definition at line 130 of file package.cpp.

setMimeTypes()

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

key	the entry within the package
mimeTypes	a list of mimeTypes

Definition at line 239 of file package.cpp.

setPath()

void Plasma::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

Since

4.3

Definition at line 185 of file package.cpp.

setRequired()

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

key	the entry within the package
required	true if this entry is required, false if not

Definition at line 229 of file package.cpp.

setServicePrefix()

void Plasma::Package::setServicePrefix

(

const QString &

servicePrefix

)

Sets service prefix.

Definition at line 150 of file package.cpp.

uninstall()

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 298 of file package.cpp.

---

The documentation for this class was generated from the following files:

• package.h
• package.cpp