KDE 4.5 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)
| 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)
[QString] | requiredDirectories (self)
[QString] | requiredFiles (self)
QString | servicePrefix (self)
| setAllowExternalPaths (self, bool allow)
| setContentsPrefix (self, QString prefix)
| 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 | 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.

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.

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

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.

[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

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

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 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.