Plasma Packages

Here's another of the topics I was going to show in the screencast: Packages. The test case was getting Apple's Dashboard Widgets to work out of the box. The rules were that we couldn't adjust any of the Plasma infrastructure at all .. it has to all work with Packages and ScriptEngines. This meant changing and improving a few things in those parts of Plasma but the result was .. well, let's take a look:

In the Add Widgets dialog the Install New Widgets button is now a menu, letting you choose between downloading from the Internet using GetHotNewStuff and DXS (where what you are about to see is even more automated) or opening a widget from a file. Our test case was the Hello World widget example from Apple.

When you select the "Open From File" entry you get this:

It's an assistant dialog that lists all known packages. It doesn't list all known applet types because to the user it shouldn't matter whether a widget is implemented in Python, Ruby, ECMA Script, XTHML+JavaScript or what-not. If they behave the same and load the same then to the user they are the same. The difference here is the package type: Apple's widgets are different from Plasma's native widgets in how they are packed up and they appear to the user as different.

I'd like to eventually automate this by trying to get plasma to figure out what kind of package it is automatically. Unfortunately right now we don't have mimetype detection for different kinds of widgets and I just haven't done enough research with all the possible package types before me to do this. This is something I want to look into for 4.2 (unless someone beats me to it, of course).

Anyways, the way we get this listing is Plasma queries for all known widget types. Every widget type advertises what "language" it is; for Mac Dashboard support the language is "dashboard". Every widget type may also advertise what sort of package structure it uses. Here's the .desktop file contents for Mac Dashboard:

[Desktop Entry]
Encoding=UTF-8
Name=Dashboard
Comment=MacOS X dashboard widget
Type=Service
ServiceTypes=Plasma/ScriptEngine
Icon=internet-web-browser

X-KDE-Library=plasma_appletscriptengine_dashboard
X-KDE-PluginInfo-Author=Zack Rusin
X-KDE-PluginInfo-Email=zackr@kde.org
X-KDE-PluginInfo-Name=dashboard
X-KDE-PluginInfo-Version=pre0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Applet
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=BSD
X-KDE-PluginInfo-EnabledByDefault=true
X-Plasma-ComponentTypes=Applet
X-Plasma-Language=dashboard
X-Plasma-PackageFormat=dashboard

Currently Plasma has package structures for wallpapers, Plasma themes and widgets. New ones can be added at runtime, however. If the package structure is static, which is to say the files are always in the same place in the package, you can do this with a simple rc file. The PackageStructure class can read and write these files as well. If the package is not static, then you can instead provide a C++ plugin that manages this. Also, if the package requires special installation routines the same C++ plugin can provide that. Both are true in the case of the Mac Dashboard widget support.

So when a Mac Dashboard widget is opened up, Plasma looks at the X-Plasma-PackageFormat entry and goes off in search of the dashboard package format. It finds it here:

[Desktop Entry]
Encoding=UTF-8
Name=Dashboard Widget
Comment=MacOS dashboard widget
Type=Service
ServiceTypes=Plasma/PackageStructure

X-KDE-Library=plasma_packagestructure_dashboard
X-KDE-PluginInfo-Author=Zack Rusin
X-KDE-PluginInfo-Email=zackr@kde.org
X-KDE-PluginInfo-Name=dashboard
X-KDE-PluginInfo-Version=pre0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Applet
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=BSD
X-KDE-PluginInfo-EnabledByDefault=true
X-Plasma-PackageFileFilter=*
X-Plasma-PackageFileMimetypes=application/zip

Mimetypes and filters for the file selection are defined, as is the library and plugin name by which to load it. At this point Plasma can now call the install method which looks like this in the dashboard package structure plugin:

bool Bundle::installPackage(const QString &archivePath,
                            const QString &packageRoot)
{
    QFile f(archivePath);
    f.open(QIODevice::ReadOnly);
    m_data = f.readAll();
    f.close();
    open();

    if (m_isValid) {
        m_tempDir->setAutoRemove(false);
        QString pluginName = "dashboard_" + m_bundleId;
        //kDebug() << "valid, so going to move it in to" << pluginName;
        KIO::CopyJob* job = KIO::move(m_tempDir->name(), packageRoot + pluginName,
                                      KIO::HideProgressInfo);
        m_isValid = job->exec();

        if (m_isValid) {
            //kDebug() << "still so good ... registering";
            Plasma::PackageMetadata data;
            data.setName(m_name);
            data.setDescription(m_description);
            data.setPluginName(pluginName);
            data.setImplementationLanguage("dashboard");
            Plasma::Package::registerPackage(data, m_iconLocation);
        }
    }

    if (!m_isValid) {
        // make sure we clean up after ourselves afterwards on failure
        m_tempDir->setAutoRemove(true);
    }

    return m_isValid;
}

What's happening in the code above is that Bundle opens the file at archivePath and makes sure it does indeed have the needed contents. It then copies it to packagRoot and registers the widget. Reigstration is accomplished by creating a PackageMetadata object, setting the relevant fields and passing it to Package::registerPackage, optionally along with the path to an icon for it. This creates an entry in the ksycoca database using a .desktop file that looks exactly like a native Plasma widget, except that this one is marked as being in the "dashboard" language.

This process all happens fairly well instantly and the result is that the widget appears in the widget listing alongside all the others:

The user sees no real difference. Places on the canvas we get:

As with native Plasmoids you can rotate it, resize it, drag it around to wherever you want, etc. Corona, Containment and even Applet are all blithely unaware anything different is going on. Zack was downloading various widgets from apple.com and trying them out and they tended to Just Work(tm).

(There are some issues currently with QtWebkit and these widgets (such as the white background and incorrect starting size), but Zack has pushed fixes for those upstream and those should be trickling down soon.)

Remember, however, that this is not specific to Mac Dashboard widgets. We can do this for any widget type we want. Indeed, Zack went ahead and did up a "native" webkit based widget for Plasma. As with Mac Dashboard widgets you do it all in HTML and use JavaScript within the webpage itself to manipulate it. Unlike Mac Dashboard, you can access Plasma goodies ... like DataEngines. So from embedded JavaScript you can fetch data from an engine and display it on your web based widget. Langauge type is "webkit". Nice.

(In fact, the Package stuff isn't specific to widgets at all. We could apply this to all sorts of after-market application add-ons.)

If you would like to add other types of widgets, I'd be happy and interested to both help you out and get resulting code into svn. Google Gadgets, Yahoo widgets, Windows Vista widgets, Opera Widgets ... they are all game. While they won't have all the features of the native Plasma widgets or cover the same kinds of topics, it would be great to be able to give people access to the whole world of widgets on their desktop.

Be Free to use the widgets you want, we have no agendas to push here.