Development/Tutorials/Collaboration/HotNewStuff/Introduction: Difference between revisions

Revision as of 09:46, 26 March 2010

Development/Tutorials/Collaboration/HotNewStuff/Introduction

Get Hot New Stuff 3 Introduction

Tutorial Series	HotNewStuff
Previous	Getting started with KDE development
What's Next	Get Hot New Stuff 3 - Upload
Further Reading	n/a

Overview

Here is a small example of an application that asks openDesktop.org for wallpapers. It lets the user install them into the system wallpaper directory.

The Code

The example consists of just one c++ source file. //khotnewstuff.cpp

include <kapplication.h>
include <kdebug.h>
include <klocale.h>
include <kcmdlineargs.h>
include <kaboutdata.h>

include <knewstuff3/downloaddialog.h>

int main(int argc, char **argv)
{

   KAboutData about("khotnewstuff_example", 0, ki18n("KHotNewStuff"), "0.4");
   about.setProgramIconName("get-hot-new-stuff");
   
   KApplication i;

   KNS3::DownloadDialog dialog(args->arg(0));
   dialog.exec();
   foreach (const KNS3::Entry& e, dialog.changedEntries()) {
       kDebug() << "Changed Entry: " << e.name();
   }

   return 0;

}

The Configuration File (.knsrc)

For this to work, a file that sets up KNewStuff khotnewstuff_example.knsrc is needed. The file has to be in kde/share/config/khotnewstuff_example.knsrc. (The name of the file is taken from the about data).

[KNewStuff3] ProvidersUrl=http://download.kde.org/ocs/providers.xml Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200 TargetDir=wallpapers Uncompress=archive

Uncompress can be one of: always, never or archive:

always: assume all downloaded files are archives and need to be extracted
never: never try to extract the file
archive: if the file is an archive, uncompress it, otherwise just pass it on

You have different options to set the target install directory:

StandardResource: standard ressouce dir, such as .kde/share/wallpapers. This is what KStandardDirs::locateLocal(name) will return.
TargetDir: a directory in the share/apps section, such as .kde/share/apps/wallpapers. This is what KStandardDirs::locateLocal("data", name) will return.

Downloaded HTML

A new option has been added for KDE 4.5. By default KNewStuff will ask if the user wants to open downloaded HTML files with a browser instead of trying to install them. This is so since most of the time HTML means a broken link or a link to a page from which the item can be downloaded. If you want to accept html (because your app actually uses KNewStuff to get html files, you should explicitly allow this: AcceptHtmlDownloads=true

Linking in CMakeLists.txt

To link against KNS3, just link against ${KDE4_KNEWSTUFF3_LIBS}. Example:

target_link_libraries(ktexteditor_codesnippets_core ${KDE4_KDEUI_LIBS} ${KDE4_KTEXTEDITOR_LIBS} ${KDE4_KNEWSTUFF3_LIBS})

Notes

If you don't like to use an external dialog, you can also use a widget instead. Just replace DownloadDialog with DownloadWidget and you're good to go. This is especially nice as additional page in existing config dialogs.

@@ Line 54: / Line 54: @@
 </code>
-Uncompress can be one of: always, never or archive:
+'''Uncompress''' can be one of: always, never or archive:
 * always: assume all downloaded files are archives and need to be extracted
 * never: never try to extract the file
 * archive: if the file is an archive, uncompress it, otherwise just pass it on
-You have different options to set the target install directory:
+You have different options to set the '''target install directory''':
 * StandardResource: standard ressouce dir, such as .kde/share/wallpapers. This is what KStandardDirs::locateLocal(name) will return.
 * TargetDir: a directory in the share/apps section, such as .kde/share/apps/wallpapers. This is what KStandardDirs::locateLocal("data", name) will return.
-A new option has been added for KDE 4.5:
+'''Downloaded HTML'''
-By default KNewStuff will ask if the user wants to open downloaded HTML files with a browser instead of trying to install them. This is so since most of the time HTML means a broken link or a link to a page from which the item can be downloaded. If you want to accept html (because your app actually uses KNewStuff to get html files, you should explicitly allow this:
+A new option has been added for KDE 4.5.
+By default KNewStuff will ask if the user wants to open ''downloaded HTML'' files with a browser instead of trying to install them. This is so since most of the time HTML means a broken link or a link to a page from which the item can be downloaded. If you want to accept html (because your app actually uses KNewStuff to get html files, you should explicitly allow this:
 <code>AcceptHtmlDownloads=true</code>