View source for Development/Tutorials/Introduction to Get Hot New Stuff

{{improve}}
{{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 ==
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.

== 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 {{path|Makefile.am}} and reconfiguring the application are to be done.

<syntaxhighlight lang="bash">
bin_PROGRAMS = myapp
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</syntaxhighlight>
          
The header files are installed under {{path|$KDEDIR/include/knewstuff/}}, so in the relevant files, they're included with statements such as:

<syntaxhighlight lang="cpp">
#include <knewstuff/downloaddialog.h>
</syntaxhighlight>
          
The following header files are provided by KNewStuff:
* {{path|downloaddialog.h}}: Easy to use download dialog
* {{path|engine.h}}: Access to the complex, but customizable background operations
* {{path|entry.h}}: (internal) Data fields of entries, such as Author or Title
* {{path|ghns.h}}: [not installed]
* {{path|knewstuffgeneric.h}}: Easy to use installation handler for the downloaded files
* {{path|knewstuff.h}}: Main knewstuff functionality
* {{path|providerdialog.h}}: Preconfigured dialog for provider selection
* {{path|provider.h}}: Provider entries, and ProviderLoader
* {{path|testnewstuff.h}}: [not installed]
* {{path|uploaddialog.h}}: Easy to use upload dialog


For more information on the background processes, please have a look at the information provided by [http://www.kstuff.org/docs/ kstuff.org]. However application authors should only need a basic understanding of those.

== 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' {{class|KAction}}. All of those have in common that they invoke a slot which will contain the actual {{class|KNewStuff}} calls. 

<code cpp-qt>
void MyApp::slotDownload()
{
  KNewStuff::DownloadDialog::open("myapp/templates");
}
</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. 

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

<syntaxhighlight lang="bash">
(to be precised)
</syntaxhighlight>

== 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 {{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. 

<syntaxhighlight lang="ini">
[KNewStuff]
StandardResource=wallpaper
InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze
</syntaxhighlight>

== 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 {{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>
#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());
</syntaxhighlight>

== 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):

<syntaxhighlight lang="ini">
[KNewStuff]
ProvidersUrl=http://where_my_xml_file_is/providers.xml
</syntaxhighlight>

To install it in the proper location, just add the following line to the {{path|Makefile.am}}:
<syntaxhighlight lang="bash">
kde_conf_DATA = ''myapprc''
</syntaxhighlight>

== Setting up a provider.xml file ==

The {{path|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 {{path|provider.xml}} file, with no upload URL specified:

<syntaxhighlight lang="xml">
<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>
</syntaxhighlight>

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