KDE 4.6 PyKDE API Reference

- KDE's Python API

# PackageStructure Class Reference

`from PyKDE4.plasma import *`

Inherits: QObject
Namespace: Plasma

## Detailed Description

PackageStructure plasma/packagestructure.h <Plasma/PackageStructure>

A description of the expected file structure of a given package type

PackageStructure defines what is in a package. This information is used to create packages and provides a way to programatically refer to contents.

An example usage of this class might be:

    PackageStructure structure;

    structure.addDirectoryDefinition("images", "pics/", i18n("Images"));
    QStringList mimetypes;
    mimetypes << "image/svg" << "image/png" << "image/jpeg";
    structure.setMimetypes("images", mimetypes);

    structure.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
    mimetypes.clear();
    mimetypes << "text/\*";
    structure.setMimetypes("scripts", mimetypes);

    structure.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
    structure.setRequired("mainscript", true);

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

Either way, PackageStructure creates a sort of "contract" between the packager and the application which is also self-documenting.

## Signals

| newWidgetBrowserFinished ()

## Methods

| __init__ (self, QObject parent=0, QString type=i18nc("A non-functional package","Invalid"))
| addDirectoryDefinition (self, QString key, QString path, QString name)
| addFileDefinition (self, QString key, QString path, QString name)
bool | allowExternalPaths (self)
QString | contentsPrefix (self)
QStringList | contentsPrefixPaths (self)
| createNewWidgetBrowser (self, QWidget parent=0)
QString | defaultPackageRoot (self)
[QString] | directories (self)
QStringList | entryList (self, QString key)
[QString] | files (self)
bool | installPackage (self, QString archivePath, QString packageRoot)
bool | isRequired (self, QString key)
QStringList | mimetypes (self, QString key)
QString | name (self, QString key)
QString | path (self, QString key)
QString | path (self)
| pathChanged (self)
| read (self, KConfigBase config)
| removeDefinition (self, QString key)
[QString] | requiredDirectories (self)
[QString] | requiredFiles (self)
QStringList | searchPath (self, QString key)
QString | servicePrefix (self)
| setAllowExternalPaths (self, bool allow)
| setContentsPrefix (self, QString prefix)
| setContentsPrefixPaths (self, QStringList prefixPaths)
| setDefaultMimetypes (self, QStringList mimetypes)
| setDefaultPackageRoot (self, QString packageRoot)
| setMimetypes (self, QString key, QStringList mimetypes)
| setPath (self, QString path)
| setRequired (self, QString key, bool required)
| setServicePrefix (self, QString servicePrefix)
QString | type (self)
bool | uninstallPackage (self, QString packageName, QString packageRoot)
| write (self, KConfigBase config)

## Static Methods

KSharedPtr<Plasma::PackageStructure> | load (QString packageFormat)

## Signal Documentation

newWidgetBrowserFinished | ( |  | ) |

Emitted when the new widget browser process completes.

Signal syntax:
  `QObject.connect(source, SIGNAL("newWidgetBrowserFinished()"), target_slot)`

## Method Documentation

__init__ | ( | self, |
|  | QObject | parent=0,
|  | QString | type=i18nc("A non-functional package","Invalid")
| ) |  |  |

Default constructor for a package structure definition

@arg type the type of package. This is often application specific.

addDirectoryDefinition | ( | self, |
|  | QString | key,
|  | QString | path,
|  | 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

addFileDefinition | ( | self, |
|  | QString | key,
|  | QString | path,
|  | 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

bool allowExternalPaths | ( |  | self ) |

Returns:
  true if paths/symlinks outside the package itself should be followed. By default this is set to false for security reasons.

QString contentsPrefix | ( |  | self ) |

Returns:
  the prefix inserted between the base path and content entries

Deprecated:
  use contentsPrefixPaths() instead.

QStringList contentsPrefixPaths | ( |  | self ) |

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

createNewWidgetBrowser | ( | self, |
|  | QWidget | parent=0
| ) |  |  |

When called, the package plugin should display a window to the user that they can use to browser, select and then install widgets supported by this package plugin with.

The user interface may be an in-process dialog or an out-of-process application.

When the process is complete, the newWidgetBrowserFinished() signal must be emitted.

Parameters:

  | parent | the parent widget to use for the widget

QString defaultPackageRoot | ( |  | self ) |

Returns:
  preferred package root. This defaults to plasma/plasmoids/

[QString] directories | ( |  | self ) |

The directories defined for this package

QStringList entryList | ( | self, |
|  | QString | key
| ) |  |  |

Get the list of files of a given type.

@arg key the type of file to look for

Returns:
  list of files by name

Since:
  4.3

[QString] files | ( |  | self ) |

The individual files, by key, that are defined for this package

bool installPackage | ( | self, |
|  | QString | archivePath,
|  | QString | packageRoot
| ) |  |  |

Installs a package matching this package structure. By default installs a native Plasma.Package.

Parameters:

  | archivePath | path to the package archive file
  | packageRoot | path to the directory where the package should be installed to

Returns:
  true on successful installation, false otherwise

bool isRequired | ( | self, |
|  | QString | key
| ) |  |  |

Returns:
  true if the item at path exists and is required

QStringList mimetypes | ( | self, |
|  | QString | key
| ) |  |  |

Returns:
  the mimetypes associated with the path, if any

QString name | ( | self, |
|  | QString | key
| ) |  |  |

Returns:
  user visible name for the given entry

QString path | ( | self, |
|  | QString | key
| ) |  |  |

Returns:
  the path to the package, or QString() if none

QString path | ( |  | self ) |

Returns:
  the path to the package, or QString() if none

pathChanged | ( |  | self ) |

Called whenever the path changes so that subclasses may take package specific actions.

read | ( | self, |
|  | KConfigBase | config
| ) |  |  |

Read a package structure from a config file.

removeDefinition | ( | self, |
|  | QString | 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

[QString] requiredDirectories | ( |  | self ) |

The required directories defined for this package

[QString] requiredFiles | ( |  | self ) |

The individual required files, by key, that are defined for this package

QStringList searchPath | ( | self, |
|  | QString | key
| ) |  |  |

Returns:
  a list of paths relative to the package root for the given entry. They are orted by importance: when searching for a file the paths will be searched in order

Since:
  4.6

QString servicePrefix | ( |  | self ) |

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

setAllowExternalPaths | ( | self, |
|  | bool | allow
| ) |  |  |

Sets whether or not external paths/symlinks can be followed by a package @arg allow true if paths/symlinks outside of the package should be followed, false if they should be rejected.

setContentsPrefix | ( | self, |
|  | QString | prefix
| ) |  |  |

Sets the prefix 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

@arg prefix the directory prefix to use

Deprecated:
  use setContentsPrefixPaths() instead.

setContentsPrefixPaths | ( | self, |
|  | 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.

@arg prefix paths the directory prefix to use

Since:
  4.6

setDefaultMimetypes | ( | self, |
|  | 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

setDefaultPackageRoot | ( | self, |
|  | QString | packageRoot
| ) |  |  |

Sets preferred package root.

setMimetypes | ( | self, |
|  | QString | 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

setPath | ( | self, |
|  | QString | path
| ) |  |  |

Sets the path to the package. Useful for package formats which do not have well defined contents prior to installation.

setRequired | ( | self, |
|  | QString | 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

setServicePrefix | ( | self, |
|  | QString | servicePrefix
| ) |  |  |

Sets service prefix.

QString type | ( |  | self ) |

Type of package this structure describes

bool uninstallPackage | ( | self, |
|  | QString | packageName,
|  | QString | packageRoot
| ) |  |  |

Uninstalls a package matching this package structure.

@arg packageName the name of the package to remove @arg packageRoot path to the directory where the package should be installed to

Returns:
  true on successful removal of the package, false otherwise

write | ( | self, |
|  | KConfigBase | config
| ) |  |  |

Write this package structure to a config file.

## Static Method Documentation

KSharedPtr<Plasma::PackageStructure> load | ( | QString | packageFormat
| ) |  |  |

Loads a package format by name.

@arg format If not empty, attempts to locate the given format, either from built-ins or via plugins.

Returns:
  a package that matches the format, if available. The caller is responsible for deleting the object.