Development/Tutorials/Plasma4/PackageStructure
Abstract
A Plasma Package is a set of files, usually shipped in a single compressed archive, that together provide one particular data or functionality addon, such as Plasmoid or a Wallpaper set. Packages may be defined for any kind of custom data (e.g. non-compiled) addons. Packages can be installed, removed, listed and updated.
Plasma::PackageStructure defines what is in a Package. This information is used to create packages and provides a way to programmatically refer to the contents. It's also used to provide an installation profile for your Packages.
plasmapkg
The plasmapkg command line tool is used to get information about Packages and install, remove or upgrade them. Run
plasmapkg --help
to get a list of available options. The most commonly used options are
-i for installing and -r for removing a package.
The Code
The Desktop File
Every PackageStructure needs a desktop file to tell plasma what package it's defining:
plasma-packagestructure-test.desktop
[Desktop Entry]
Name=Test
Comment=Test Package Structure
Type=Service
X-KDE-ServiceTypes=Plasma/PackageStructure
X-KDE-PluginInfo-Name=Plasma/Test
X-KDE-Library=plasma_packagestructure_test
X-KDE-PluginInfo-Author=Farhad Hedayati Fard
X-KDE-PluginInfo-Email=hf.farhad@gmail.com
X-KDE-PluginInfo-Name=org.myproject.test
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-License=GPLv3+
X-KDE-PluginInfo-EnabledByDefault=true
X-Plasma-PackageFileFilter=*.test
X-Plasma-PackageFileMimetypes=application/zip
The most important fields are:
- Name, Comment and Type fields, which are required for all desktop files.
- X-KDE-ServiceTypes field which tells plasma that this is a PackageStructure
- X-KDE-PluginInfo-Name field which should be identical to the name used in your code (discussed later).
- X-KDE-Library field which tells plasma how to load/install the packages with this package structure.
- X-KDE-PluginInfo-Name field which should be identical to the name of dataengine/plasmoid that uses this PackageStructure.
The Header File
testpackage.h
- ifndef TESTPACKAGE_H
- define TESTPACKAGE_H
// We need this header since we are inheriting it
- include <plasma/packagestructure.h>
/**
This PackageStructe provides an structure for packages used by the test
DataEngine.
- /
class TestPackage : public Plasma::PackageStructure
{
public:
// Every PackageStructure needs an explicit constructor with these arguments
explicit TestPackage(QObject *parent = 0, const QVariantList& args = QVariantList());
};
K_EXPORT_PLASMA_PACKAGESTRUCTURE(test, TestPackage)
- endif // TESTPACKAGE_H
The Main Code
testpackage.cpp
- include "testpackage.h"
- include "plasma/applet.h"
- include "plasma/package.h"
/**
We pass Plasma/Test as the type to the Plasma::PackageStructure. this string
should be identical to the "X-KDE-PluginInfo-Name" in the desktop file,
otherwise plasmapkg won't recognize your package and you'll get an this error
when trying to install your packages:
Could not find a suitable installer for package of type Plasma/Test
- /
TranslatorPackage::TranslatorPackage( QObject *parent, const QVariantList& args )
: Plasma::PackageStructure( parent, QLatin1String( "Plasma/Test" ) )
{
Q_UNUSED( args )
// tell plasma about your package's directory structure with addDirectoryDefinition
addDirectoryDefinition( "images", QLatin1String( "images" ), i18n( "Images" ) );
// what does the directory contain?
QStringList mimetypes;
mimetypes << QLatin1String( "image/svg+xml" ) << QLatin1String( "image/png" ) << QLatin1String( "image/jpeg" );
setMimetypes( "images", mimetypes );
addDirectoryDefinition( "scripts", QLatin1String( "code" ), i18n( "Executable Scripts" ) );
mimetypes.clear();
mimetypes << QLatin1String( "text/*" );
setMimetypes( "scripts", mimetypes );
// tell plasma what is the name of script in the package.
addFileDefinition( "mainscript", QLatin1String( "code/main.js" ), i18n( "Main Script File" ) );
// tell plasma where to install your package.
// normally this would be prepended with ~/.kde4/share/apps/
// so the final path to your package after installation is ~/.kde4/share/apps/plasma/test/
setDefaultPackageRoot( QLatin1String( "plasma/test/" ) );
// You'll need to use this service prefix when you want to access "test" packages.
setServicePrefix( QLatin1String( "plasma-test-" ) );
}
File Definition
in this Example, For simplicity's sake, I've added code/main.js file definition. This way your packages support only js scripts. But if you want to support a larger set of scripting languages, you should leave this to code/main, and then in your dataengine/plasmoid, when trying to use the installed packages, set the extension of the script file like this:
// get path to your installed packages
const QString path = KStandardDirs::locate( "data", QLatin1String( "plasma/test/" ) + pluginName + QLatin1Char( '/' ) );
if (!path.isEmpty()) {
// pass path to the package and new TestPackage() as package type to Plasma::Package
m_package = new Plasma::Package(path, packageStructure());
if (m_package->isValid()) {
// get mainscript's file path (now code/main - without file extension)
const QString mainscript = m_package->path() + m_package->structure()->contentsPrefix() +
m_package->structure()->path( "mainscript" );
QFileInfo info( mainscript );
// get supported scripting bindings, you'll find how to do this in kross tutorials.
QStringList extensions = supportedScriptLangs();
// add supported extensions to the mainscript file path and check if it exists.
for ( int i = 0; i < extensions.count() && !info.exists(); ++i ) {
info.setFile( mainscript + extensions.value( i ) );
if (info.exists()) break;
}
// if a supported script exists, use it!
if ( info.exists() ) {
m_action = new Kross::Action(this, pluginName);
m_action->setFile(info.filePath());
m_action->trigger();
}
}
}
Build and Install
the CMakeLists.txt file tells cmake how to build and install your project, add the following lines to this file to for this test project:
set(testpackage_SRC testpackage.cpp)
kde4_add_plugin( plasma-packagestructure-test ${testpackage_SRC} )
target_link_libraries( plasma-packagestructure-test ${KDE4_KDEUI_LIBS} ${KDE4_PLASMA_LIBS} )
install( TARGETS plasma-packagestructure-test DESTINATION ${PLUGIN_INSTALL_DIR} )
install( FILES plasma-packagestructure-test.desktop DESTINATION ${SERVICES_INSTALL_DIR} )