Development/Tutorials/Introduction to Get Hot New Stuff

Warning

This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo

Tip

Note: This page deals with content related to KDE 3. If you are developing for KDE 4, this information might not be valid anymore.

KDE 4

Please read the KDE 4 tutorials about get hot new stuff, unless you really work on KDE 3 apps.

Introduction

Similar to how programming languages shifted focus from algorithms to data structures in the 70s, desktop application development emphasizes more and more on user data, i.e. data intentionally produced or consumed by the user. Both on the internet and in corporate intranets, sharing this data is considered an easy way to customize desktops and to advertise one's creativity. The 'Get Hot New Stuff' (GHNS) framework in KDE exists to support this approach, and the KNewStuff library is the key for application authors to enable GHNS.

Preparations

The first steps are usually made in preparing the usage of KNewStuff. For this matter, the library must be available (a task which could be done using autoconf, but since it's part of kdelibs, we simply assume it's available with any recent KDE installation.) Authors of 3rd pary applications can ensure the availability as part of kdepim-libs in KDE 3.2 using the AC_KNEWSTUFF macro. It must also be included in the set of libraries against which the application is linked, so modifying the Makefile.am and reconfiguring the application are to be done.

bin_PROGRAMS = myapp myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff

The header files are installed under $KDEDIR/include/knewstuff/, so in the relevant files, they're included with statements such as:

1. include <knewstuff/downloaddialog.h>

The following header files are provided by KNewStuff:

• downloaddialog.h: Easy to use download dialog
• engine.h: Access to the complex, but customizable background operations
• entry.h: (internal) Data fields of entries, such as Author or Title
• ghns.h: [not installed]
• knewstuffgeneric.h: Easy to use installation handler for the downloaded files
• knewstuff.h: Main knewstuff functionality
• providerdialog.h: Preconfigured dialog for provider selection
• provider.h: Provider entries, and ProviderLoader
• testnewstuff.h: [not installed]
• uploaddialog.h: Easy to use upload dialog

For more information on the background processes, please have a look at the information provided by kstuff.org. However application authors should only need a basic understanding of those.

Downloading Data

Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' KAction. All of those have in common that they invoke a slot which will contain the actual KNewStuff calls.

void MyApp::slotDownload() {

 KNewStuff::DownloadDialog::open("myapp/templates");

}

This is all. If desired, more control can be exercised on the whole download process, as outlined below. For the beginning, the above is already fully functional, and should be used at first.

Downloading in Detail

The example above implicitely constructs an internal Engine object, retrieves the directory list, fetches the provider lists specified in the directory, and the entries in each of the provider lists, compares them to the data files previously installed, and displays them in the download dialog. This dialog in turn handles all the installation issues. Of course there is no magic involved, and for more control about the subtasks, the following is recommended:

(to be precised)

Installation

Similar to the provider list, the installation procedures are described in the application's configuration file. The default (if these entries are missing) is to just download the file to a temporary location, which is not useful in most of the cases. There are two entries: target location, and post-installation command. The target location can either be StandardResource, matching the KDE resource types, or TargetDir, matching an application directory under $KDEHOME/share/apps/appname. The post installation command can be a binary with '%f' as parameter (note the single quotes to prevent string format attacks), but it can as well be a DCOP call, so the application can directly work with the data.

[KNewStuff] StandardResource=wallpaper InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze

Uploads

The beginning of the upload process works similar to downloads. A MasterServer or ProvidersUrl is used to retrieve the provider list, and one of the providers is selected by the user. Only providers which allow uploads are taken into account. After this selection however, the differences begin. The user has to fill in the necessary information such as title, author name or version number into the upload dialog. Also, the payload and preview files have to be selected, this however will in most cases be the application's task. In Kamikaze, the level file is pre-rendered to an invisible QCanvas, and the resulting graphics is minimized and automatically specified for the upload. The upload will then happen using the protocol accepted by the provider, which in most cases will be anonymous FTP.

1. include <knewstuff/knewstuffgeneric.h>
2. include <knewstuff/engine.h>
3. include <knewstuff/uploaddialog.h>

// ... QString file, previewfile; KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this); ns->upload(file.name(), previewfile.name());

Finding the provider

In order to connect to the provider, you have to add the KNewStuff configuration to the config file of the application.

This can be done by adding the following lines to the myapprc file (create the file if there was none):

[KNewStuff] ProvidersUrl=http://where_my_xml_file_is/providers.xml

To install it in the proper location, just add the following line to the Makefile.am: kde_conf_DATA = myapprc

Setting up a provider.xml file

The provider.xml file holds the general information about the new stuff source (for example the name or the icon), and - most important thing - the location to the XML file containing the stuff for the application.

Here it is a simple provider.xml file, with no upload URL specified:

<syntaxhighlight lang="xml"> <provider downloadurl="http://where_my_newstuff_are/knewstuff.xml"

         nouploadurl=""
         icon="http://where_my_newstuff_are/myapp_newstuff.png">
 <title>New stuff for MyApp!</title>

</provider>

Conclusion

Sharing creativity should become a default property of modern desktops, and KDE once again leads the pack by providing both upload and download facilities. If enough applications of different areas make use of them, it helps users to be more productive and have more fun with their computer.