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.

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.

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=
</code>
::'''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:
<syntaxhighlight lang="text">
TargetDir=
InstallPath=
StandardResource=
AbsoluteInstallPath=
</code>
:* 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:
<syntaxhighlight lang="text">
CustomName=
CachePolicy=
ChecksumPolicy=
SignaturePolicy=
Scope=
</code>
:install the file using CMake install macro like this
<syntaxhighlight lang="text">
install( FILES yourdata.knsrc DESTINATION ${CONFIG_INSTALL_DIR} )
</code>
:at this point, you can test your knsrc file with khotnewstuff4 like so:
<syntaxhighlight lang="text">
khotnewstuff4 yourdata.knsrc
</code>
:it should show you a download dialog of the data available on your provider(s).
=== 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
<syntaxhighlight lang="text">
static KNS::Entry::List download();
</code>
: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:
<syntaxhighlight lang="text">
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);
</code>
: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:
<syntaxhighlight lang="text">
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();
}
}
</code>
:Taken from plasma/containments/desktop/backgrounddialog.cpp