KDE Tutorial: Get Hot New Stuff

Introduction

Since KDE 3.2, applications can use a central framework for downloading and uploading media files such as wallpapers, game levels, spreadsheet templates and so on. The KNewStuff library is flexible enough to allow for both easy-to-use invocation and detailed control about what's going on. In this tutorial, 2 applications are highlighted to cover these cases: Kamikaze and KOrganizer.

Kamikaze

As an external KDE application, the very first task to do is to check whether the KNewStuff library is actually available. The code could use version checking (KDE_VERSION >= 3.2), but since the library must be linked in conditionally, an autoconf macro is provided here.

All the application author has to do is to call AC_KNEWSTUFF in configure.ac, and then check for HAVE_KNEWSTUFF (defined in config.h) and use $(KNEWSTUFF) in the application's Makefile.am (which will be set to -lknewstuff if available). The source is modified as follows:
  1. Include knewstuff/downloaddialog.h into your main window source file:
    #include <knewstuff/downloaddialog.h>
  2. Add a menu entry for knewstuff:
    gamemenu->insertItem(KGlobal::iconLoader()->loadIcon("knewstuff", KIcon::Small), i18n("&Get Levels"), game_newlevels);
gamemenu->insertSeparator();
  3. On menu invokation, actually show the knewstuff dialog:
    KNS::DownloadDialog::open("kamikaze/level");

The game Kamikaze provides an easy way to get new levels.


This is the dialog including only Kamikaze levels.

KOrganizer

KOrganizer is part of KDE CVS, and thus doesn't need to check for library availability. Furthermore, the application needs more fine-grained control over the installation of new content, especially an updated calendar view if new calendars are installed.

Beside the steps mentioned above, the following is to be done:
  1. Set up an object from a class derived from KNewStuff:
    if ( !mNewStuff ) mNewStuff = new KONewStuff( mCalendarView );
  2. Invoke the download method():
    mNewStuff->download();
In this case, the dialog is automatically called by the KNewStuff Engine. Note that if files just have to be copied somewhere, a convenience KNewStuff-derived class is provided: KNewStuffGeneric. This class takes as the first argument for the constructor the type of the data.


The help menu of KOrganizer containing the download and upload menu items.


A dedicated KNewStuff-derived object can display additional information.


Installed items are marked with a green ok sign, while outdated ones are marked with a history icon.

Josef Spillner <spillner kde org>
29.08.2003