Difference between revisions of "Development/Tutorials/Collaboration/HotNewStuff/Introduction"

Jump to: navigation, search
m (Text replace - "<code>" to "<syntaxhighlight lang="text">")
Line 50: Line 50:
 
The file has to be in ''kde/share/config/khotnewstuff_example.knsrc''.
 
The file has to be in ''kde/share/config/khotnewstuff_example.knsrc''.
  
<code>
+
<syntaxhighlight lang="text">
 
[KNewStuff3]
 
[KNewStuff3]
 
Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200
 
Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200
Line 74: Line 74:
 
A new option has been added for KDE 4.5.
 
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:
 
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>
+
<syntaxhighlight lang="text">AcceptHtmlDownloads=true</code>
  
 
'''ProvidersUrl'''
 
'''ProvidersUrl'''
Line 80: Line 80:
 
Starting with KDE 4.5 this is optional, and if you just want to use what KDE provides as default (http://download.kde.org/ocs/providers.xml, currently openDesktop.org), leave this out. The advantage of not specifying this field is that users can add more providers using the attica kcm (kcmshell4 kcm_attica).
 
Starting with KDE 4.5 this is optional, and if you just want to use what KDE provides as default (http://download.kde.org/ocs/providers.xml, currently openDesktop.org), leave this out. The advantage of not specifying this field is that users can add more providers using the attica kcm (kcmshell4 kcm_attica).
 
Only if you have to (because you need a different provider) use:
 
Only if you have to (because you need a different provider) use:
<code>ProvidersUrl=http://download.kde.org/ocs/providers.xml</code>
+
<syntaxhighlight lang="text">ProvidersUrl=http://download.kde.org/ocs/providers.xml</code>
  
 
==== Linking in CMakeLists.txt  ====
 
==== Linking in CMakeLists.txt  ====
Line 86: Line 86:
 
To link against KNS3, just link against ''${KDE4_KNEWSTUFF3_LIBS}''. Example:  
 
To link against KNS3, just link against ''${KDE4_KNEWSTUFF3_LIBS}''. Example:  
  
<code>
+
<syntaxhighlight lang="text">
 
target_link_libraries(ktexteditor_codesnippets_core
 
target_link_libraries(ktexteditor_codesnippets_core
 
${KDE4_KDEUI_LIBS} ${KDE4_KTEXTEDITOR_LIBS} ${KDE4_KNEWSTUFF3_LIBS})
 
${KDE4_KDEUI_LIBS} ${KDE4_KTEXTEDITOR_LIBS} ${KDE4_KNEWSTUFF3_LIBS})

Revision as of 21:44, 29 June 2011


Contents

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 - Updates
Further Reading   API Documentation

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

  1. include <kapplication.h>
  2. include <kdebug.h>
  3. include <klocale.h>
  4. include <kcmdlineargs.h>
  5. include <kaboutdata.h>
  1. 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. If you don't pass a file name to the dialog, the name of the file is taken from the about data (application name). If you want to use different dialogs in one application, just create multiple .knsrc files, such as krita_brushes.knsrc and krita_palettes.knsrc for example.

The file has to be in kde/share/config/khotnewstuff_example.knsrc.

[KNewStuff3]
Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200
TargetDir=wallpapers
Uncompress=archive
</code> 
 
'''Uncompress''' can be one of:
* 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.
* XdgTargetDir: a directory in the $XDG_DATA_HOME directory such as .local/share/wallpapers (since KDE 4.5)
 
 
'''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:
<syntaxhighlight lang="text">AcceptHtmlDownloads=true</code>
 
'''ProvidersUrl'''
The data has to come from somewhere, right? Up until KDE SC 4.5 you '''must''' specify ProvidersUrl with an url to the providers.xml file.
Starting with KDE 4.5 this is optional, and if you just want to use what KDE provides as default (http://download.kde.org/ocs/providers.xml, currently openDesktop.org), leave this out. The advantage of not specifying this field is that users can add more providers using the attica kcm (kcmshell4 kcm_attica).
Only if you have to (because you need a different provider) use:
<syntaxhighlight lang="text">ProvidersUrl=http://download.kde.org/ocs/providers.xml</code>
 
==== Linking in CMakeLists.txt  ====
 
To link against KNS3, just link against ''${KDE4_KNEWSTUFF3_LIBS}''. Example: 
 
<syntaxhighlight lang="text">
target_link_libraries(ktexteditor_codesnippets_core
${KDE4_KDEUI_LIBS} ${KDE4_KTEXTEDITOR_LIBS} ${KDE4_KNEWSTUFF3_LIBS})
</code> 
 
==== Using a Widget instead of the Dialog  ====
 
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.<br>

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal