Difference between revisions of "Development/Tutorials/K Hot New Stuff2"

Latest revision as of 21:52, 29 June 2011

This tutorial informs about how to use Get Hot New Stuff collaborative data sharing features in your KDE application. Complementary to this tutorial, there is a porting guide for KDE 3 developers and another tutorial in SVN. The KNS2-enabled application list is also a good reference to find similar applications.

[edit] Terminology

First some basic terminology just to get us all on the same page. KHotNewStuff2 is the new library that implements the GHNS freedesktop.org specification for downloading and uploading user data. It will also support DXS (Desktop Exchange Service)

[edit] Use it in your application

There are a many good examples for how to use khotnewstuff2 in the KDE-Edu module. Look at their source code for examples if needed, but it's basically a 2-part process to get download into your app.

[edit] First write a .knsrc file.

A .knsrc file is just a file telling the library which options to use for a given application. It also lists where providers can be found, where uploads should be sent, etc. Anyway, the format of the file is an ini file with one group:

[KNewStuff2]
ProvidersUrl=
InstallationCommand=
Uncompress=

NOTE: InstallationCommand is optional, and if included will be invoked after each item is downloaded.

NOTE: Uncompress is optional, and if included will try to uncompress all downloads into the target folder according to the mime-type of the file.

• Uncompress possible values as of r794016 are
• "always" - always attempt to uncompress (old values of "true" are seen as "always"
• "archive" - uncompress if it's an archive but copy otherwise
• "never" - (default) never attempt to uncompress

One of the following is required to tell where downloads should go:

TargetDir=
InstallPath=
StandardResource=
AbsoluteInstallPath=

• TargetDir installs to KStandardDirs::locateLocal("data") + TargetDir + "/"
• StandardResource installs to KStandardDirs::locateLocal(StandardResource)
• InstallPath installs to QDir::home().path() + "/" + InstallPath
• AbsoluteInstallPath installs to AbsoluteInstallPath + "/"

NOTE: AbsoluteInstallPath is not portable (/boot/grub is probably not a valid path except on linux), so should not be used in anything that is meant to run on all our platforms.

And the following values are currently read, though not used yet:

CustomName=
CachePolicy=
ChecksumPolicy=
SignaturePolicy=
Scope=

install the file using CMake install macro like this

install( FILES yourdata.knsrc  DESTINATION  ${CONFIG_INSTALL_DIR} )

at this point, you can test your knsrc file with khotnewstuff4 like so:

khotnewstuff4 yourdata.knsrc

it should show you a download dialog of the data available on your provider(s).

[edit] Make your application launch the KNS ui with your knsrc file.

There are many examples of using KNS in code, kde-edu apps, kdegames apps, plasma, some kcm modules, etc. Basically there are two options at this time for invoking the download dialog.

Option 1. Use the static call. KNewStuff::Engine has a static method

static KNS::Entry::List download();

if you use this method, your knsrc file must have the same name as your KGlobal::activeComponent().componentName(), it will create an Engine object, initialize it with the knsrc file, and call downloadDialogModal, then before returning it will copy the list of modified (installed, uninstalled, etc.) entries. Use is like this:

    KNS::Entry::List entries = KNS::Engine::download();
    // list of changed entries
    foreach(KNS::Entry* entry, entries) {
        // care only about installed ones
        if (entry->status() == KNS::Entry::Installed) {
            // do something with the installed entries
            }
        }
    }
    qDeleteAll(entries);

Taken from kdeedu/parley/src/parleydocument.cpp

NOTE: Since the Ently::List is a copy of entries from the engine that has now been deleted, you are responsible for cleanup of the allocated Entry(s).

Option 2. Allocate your own Engine object. This method is more flexible, in that you can name your knsrc file anything you want, since you call Engine::init yourself. You also don't have to worry about deleting the EntryList that is returned, since your Engine object owns it. This method is done like so:

    KNS::Engine engine(0);
    if (engine.init("wallpaper.knsrc")) {
        KNS::Entry::List entries = engine.downloadDialogModal(this);
 
        if (entries.size() > 0) {
	    // do something with the modified entries here if you want
 
            // such as rescaning your data folder or whatnot
            m_model->reload();
        }
    }

Taken from plasma/containments/desktop/backgrounddialog.cpp