Difference between revisions of "Development/Tutorials/Introduction to Get Hot New Stuff"

Jump to: navigation, search
m (Preparations: bash -> make)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{improve}}
 
{{improve}}
 
{{KDE3}}  
 
{{KDE3}}  
 +
 +
== KDE 4 ==
 +
Please read the [[Development/Tutorials#Get_Hot_New_Stuff|KDE 4 tutorials]] about get hot new stuff, unless you really work on KDE 3 apps.
  
 
== Introduction ==
 
== Introduction ==
Line 8: Line 11:
 
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 {{path|Makefile.am}} and reconfiguring the application are to be done.
 
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 {{path|Makefile.am}} and reconfiguring the application are to be done.
  
<code>
+
<syntaxhighlight lang="make">
 
bin_PROGRAMS = myapp
 
bin_PROGRAMS = myapp
 
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
 
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</code>
+
</syntaxhighlight>
 
            
 
            
 
The header files are installed under {{path|$KDEDIR/include/knewstuff/}}, so in the relevant files, they're included with statements such as:
 
The header files are installed under {{path|$KDEDIR/include/knewstuff/}}, so in the relevant files, they're included with statements such as:
  
<code cpp>
+
<syntaxhighlight lang="cpp">
 
#include <knewstuff/downloaddialog.h>
 
#include <knewstuff/downloaddialog.h>
</code>
+
</syntaxhighlight>
 
            
 
            
 
The following header files are provided by KNewStuff:
 
The following header files are provided by KNewStuff:
Line 38: Line 41:
 
Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' {{class|KAction}}. All of those have in common that they invoke a slot which will contain the actual {{class|KNewStuff}} calls.  
 
Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' {{class|KAction}}. All of those have in common that they invoke a slot which will contain the actual {{class|KNewStuff}} calls.  
  
<code cpp-qt>
+
<syntaxhighlight lang="cpp-qt">
 
void MyApp::slotDownload()
 
void MyApp::slotDownload()
 
{
 
{
 
   KNewStuff::DownloadDialog::open("myapp/templates");
 
   KNewStuff::DownloadDialog::open("myapp/templates");
 
}
 
}
</code>
+
</syntaxhighlight>
  
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.  
+
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 ==
 
== 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:  
 
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:  
  
<code>
+
<syntaxhighlight lang="bash">
 
(to be precised)
 
(to be precised)
</code>
+
</syntaxhighlight>
  
 
== Installation ==
 
== Installation ==
Line 58: Line 61:
 
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 {{path|$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.  
 
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 {{path|$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.  
  
<code ini>
+
<syntaxhighlight lang="ini">
 
[KNewStuff]
 
[KNewStuff]
 
StandardResource=wallpaper
 
StandardResource=wallpaper
Line 64: Line 67:
  
 
TargetDir=kamikaze
 
TargetDir=kamikaze
</code>
+
</syntaxhighlight>
  
 
== Uploads ==
 
== Uploads ==
Line 70: Line 73:
 
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 {{qt3|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.
 
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 {{qt3|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.
  
<code cpp-qt>
+
<syntaxhighlight lang="cpp-qt">
 
#include <knewstuff/knewstuffgeneric.h>
 
#include <knewstuff/knewstuffgeneric.h>
 
#include <knewstuff/engine.h>
 
#include <knewstuff/engine.h>
Line 78: Line 81:
 
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
 
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
 
ns->upload(file.name(), previewfile.name());
 
ns->upload(file.name(), previewfile.name());
</code>
+
</syntaxhighlight>
  
 
== Finding the provider ==
 
== Finding the provider ==
Line 86: Line 89:
 
This can be done by adding the following lines to the ''myapprc'' file (create the file if there was none):
 
This can be done by adding the following lines to the ''myapprc'' file (create the file if there was none):
  
<code ini>
+
<syntaxhighlight lang="ini">
 
[KNewStuff]
 
[KNewStuff]
 
ProvidersUrl=http://where_my_xml_file_is/providers.xml
 
ProvidersUrl=http://where_my_xml_file_is/providers.xml
</code>
+
</syntaxhighlight>
  
 
To install it in the proper location, just add the following line to the {{path|Makefile.am}}:
 
To install it in the proper location, just add the following line to the {{path|Makefile.am}}:
<code>
+
<syntaxhighlight lang="bash">
 
kde_conf_DATA = ''myapprc''
 
kde_conf_DATA = ''myapprc''
</code>
+
</syntaxhighlight>
  
 
== Setting up a provider.xml file ==
 
== Setting up a provider.xml file ==
Line 102: Line 105:
 
Here it is a simple {{path|provider.xml}} file, with no upload URL specified:
 
Here it is a simple {{path|provider.xml}} file, with no upload URL specified:
  
<code xml>
+
<syntaxhighlight lang="xml">
 
<provider downloadurl="http://where_my_newstuff_are/knewstuff.xml"
 
<provider downloadurl="http://where_my_newstuff_are/knewstuff.xml"
 
           nouploadurl=""
 
           nouploadurl=""
Line 108: Line 111:
 
   <title>New stuff for MyApp!</title>
 
   <title>New stuff for MyApp!</title>
 
</provider>
 
</provider>
</code>
+
</syntaxhighlight>
  
 
== Conclusion ==
 
== 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.
 
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.

Latest revision as of 11:29, 30 June 2011

noframe
 
This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo


Ktip.png
 
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.


Contents

[edit] KDE 4

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

[edit] 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.

[edit] 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:

#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.

[edit] 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.

[edit] 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)

[edit] 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

[edit] 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.

#include <knewstuff/knewstuffgeneric.h>
#include <knewstuff/engine.h>
#include <knewstuff/uploaddialog.h>
// ...
QString file, previewfile;
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
ns->upload(file.name(), previewfile.name());

[edit] 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''

[edit] 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:

<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>

[edit] 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.


This page was last modified on 30 June 2011, at 11:29. This page has been accessed 16,970 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal