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

From KDE TechBase
No edit summary
(The tutorial pointed to an ancient location. It needs further work, but at least now it won't cause more undesired load.)
 
(25 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Collaboration/HotNewStuff/Introduction}}
 


{{TutorialBrowser|
{{TutorialBrowser|
Line 5: Line 5:
name=Get Hot New Stuff 3 Introduction|
name=Get Hot New Stuff 3 Introduction|
pre=[[Getting_Started|Getting started with KDE development]]|
pre=[[Getting_Started|Getting started with KDE development]]|
next=[[Development/Tutorials/Collaboration/HotNewStuff/Upload|Get Hot New Stuff 3 - Upload]]|
next=[[Development/Tutorials/Collaboration/HotNewStuff/Updates|Get Hot New Stuff 3 - Updates]]|
reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/knewstuff/html/classKNS3_1_1DownloadDialog.html API Documentation]
}}  
}}  
{{Improve}}


== Overview  ==
== Overview  ==
Line 14: Line 17:
==== The Code  ====
==== The Code  ====


The example consists of just one c++ source file. <code cppqt="cppqt">
The example consists of just one c++ source file. <syntaxhighlight lang="cpp-qt">
//khotnewstuff.cpp
//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)
int main(int argc, char **argv)
{
{
     KAboutData about("khotnewstuff_example", 0, ki18n("KHotNewStuff"), "0.4");
     QCoreApplication::setApplicationName(QStringLiteral("khotnewstuff"));
     about.setProgramIconName("get-hot-new-stuff");
    QCoreApplication::setApplicationVersion(QStringLiteral("0.4"));
   
     QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
     KApplication i;
    QApplication::setApplicationDisplayName(i18n("KHotNewStuff"));
 
     QApplication i(argc, argv);


     KNS3::DownloadDialog dialog(args->arg(0));
     if (i.arguments().count() > 1) {
    dialog.exec();
        QString configfile = QLatin1String(argv[1]);
    foreach (const KNS3::Entry& e, dialog.changedEntries()) {
        QPointer<KNS3::DownloadDialog> dialog = new KNS3::DownloadDialog(configfile);
        kDebug() << "Changed Entry: " << e.name();
        dialog->exec();
        foreach (const KNS3::Entry& e, dialog->changedEntries()) {
            qCDebug(KNEWSTUFF) << "Changed Entry: " << e.name();
        }
        delete dialog;
    } else {
        return -1;
     }
     }
     return 0;
     return 0;
}
}
</code>  
</syntaxhighlight>


==== 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 Configuration File (.knsrc)  ====
The file has to be in ''kde/share/config/khotnewstuff_example.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).  


<code>
<syntaxhighlight lang="text">
[KNewStuff3]
[KNewStuff3]
ProvidersUrl=http://download.kde.org/ocs/providers.xml
Name=Wallpapers
Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200
Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200
TargetDir=wallpapers
TargetDir=wallpapers
Uncompress=archive
Uncompress=archive
</code>  
</syntaxhighlight>  


Uncompress can be one of: always, never or archive:
'''Uncompress''' can be one of:
* always: assume all downloaded files are archives and need to be extracted
* always: assume all downloaded files are archives and need to be extracted
* never: never try to extract the file
* never: never try to extract the file
* archive: if the file is an archive, uncompress it, otherwise just pass it on
* 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.
* 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.
* 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
'''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:
<syntaxhighlight lang="text">AcceptHtmlDownloads=true</syntaxhighlight>
'''ProvidersUrl'''
The ProvidersUrl is optional, and if you just want to use what KDE provides as default (http://autoconfig.kde.org/ocs/providers.xml, currently store.kde.org), leave this out. The advantage of not specifying this field is that users can add more providers using the attica kcm (kcmshell5 kcm_attica).
Only if you have to (because you need a different provider) use:
<syntaxhighlight lang="text">ProvidersUrl=http://autoconfig.kde.org/ocs/providers.xml</syntaxhighlight>
==== Linking in CMakeLists.txt  ====
To link against KNS3, just link against ''KF5::NewStuff''. Example:
<syntaxhighlight lang="cmake">
target_link_libraries(ktexteditor_codesnippets_core Qt5::Widgets KF5::TextEditor KF5::NewStuff)
</syntaxhighlight>


==== Linking in CMakeLists.txt ====
==== Using a Widget instead of the Dialog  ====
To link against KNS3, just link against ''${KDE4_KNEWSTUFF3_LIBS}''. Example:


<code>
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>
target_link_libraries(ktexteditor_codesnippets_core
${KDE4_KDEUI_LIBS} ${KDE4_KTEXTEDITOR_LIBS} ${KDE4_KNEWSTUFF3_LIBS})
</code>

Latest revision as of 11:51, 30 January 2020


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
Warning
This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo


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

int main(int argc, char **argv)
{
    QCoreApplication::setApplicationName(QStringLiteral("khotnewstuff"));
    QCoreApplication::setApplicationVersion(QStringLiteral("0.4"));
    QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
    QApplication::setApplicationDisplayName(i18n("KHotNewStuff"));

    QApplication i(argc, argv);

    if (i.arguments().count() > 1) {
        QString configfile = QLatin1String(argv[1]);
        QPointer<KNS3::DownloadDialog> dialog = new KNS3::DownloadDialog(configfile);
        dialog->exec();
        foreach (const KNS3::Entry& e, dialog->changedEntries()) {
            qCDebug(KNEWSTUFF) << "Changed Entry: " << e.name();
        }
        delete dialog;
    } else {
        return -1;
    }
    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]
Name=Wallpapers
Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200
TargetDir=wallpapers
Uncompress=archive

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


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:

AcceptHtmlDownloads=true

ProvidersUrl The ProvidersUrl is optional, and if you just want to use what KDE provides as default (http://autoconfig.kde.org/ocs/providers.xml, currently store.kde.org), leave this out. The advantage of not specifying this field is that users can add more providers using the attica kcm (kcmshell5 kcm_attica). Only if you have to (because you need a different provider) use:

ProvidersUrl=http://autoconfig.kde.org/ocs/providers.xml

Linking in CMakeLists.txt

To link against KNS3, just link against KF5::NewStuff. Example:

target_link_libraries(ktexteditor_codesnippets_core Qt5::Widgets KF5::TextEditor KF5::NewStuff)

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.