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

    From KDE TechBase
    m (some templates more)
    ({{file}} -> {{path}})
    Line 5: Line 5:


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




    Line 90: Line 90:
    </code>
    </code>


    To install it in the proper location, just add the following line to the Makefile.am:
    To install it in the proper location, just add the following line to the {{path|Makefile.am}}:
    <code>
    <code>
    kde_conf_DATA = ''myapprc''
    kde_conf_DATA = ''myapprc''
    Line 97: Line 97:
    == Setting up a provider.xml file ==
    == 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.
    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 provider.xml file, with no upload URL specified:
    Here it is a simple {{path|provider.xml}} file, with no upload URL specified:


    <code xml>
    <code xml>

    Revision as of 00:07, 29 May 2007

    Warning
    This section needs improvements: Please help us to

    cleanup confusing sections and fix sections which contain a todo


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

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

    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.

    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)

    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

    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.

    1. include <knewstuff/knewstuffgeneric.h>
    2. include <knewstuff/engine.h>
    3. include <knewstuff/uploaddialog.h>

    // ... QString file, previewfile; KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this); ns->upload(file.name(), previewfile.name());

    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

    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>

    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.