Development/Tutorials/K Hot New Stuff2: Difference between revisions

    From KDE TechBase
    m (Text replace - "<code>" to "<syntaxhighlight lang="text">")
    m (Text replace - "</code>" to "</syntaxhighlight>")
    Line 16: Line 16:
    InstallationCommand=
    InstallationCommand=
    Uncompress=
    Uncompress=
    </code>
    </syntaxhighlight>


    ::'''NOTE''': InstallationCommand is optional, and if included will be invoked after each item is downloaded.
    ::'''NOTE''': InstallationCommand is optional, and if included will be invoked after each item is downloaded.
    Line 32: Line 32:
    StandardResource=
    StandardResource=
    AbsoluteInstallPath=
    AbsoluteInstallPath=
    </code>
    </syntaxhighlight>


    :* TargetDir installs to KStandardDirs::locateLocal("data") + TargetDir + "/"
    :* TargetDir installs to KStandardDirs::locateLocal("data") + TargetDir + "/"
    Line 47: Line 47:
    SignaturePolicy=
    SignaturePolicy=
    Scope=
    Scope=
    </code>
    </syntaxhighlight>
    :install the file using CMake install macro like this
    :install the file using CMake install macro like this
    <syntaxhighlight lang="text">
    <syntaxhighlight lang="text">
    install( FILES yourdata.knsrc  DESTINATION  ${CONFIG_INSTALL_DIR} )
    install( FILES yourdata.knsrc  DESTINATION  ${CONFIG_INSTALL_DIR} )
    </code>
    </syntaxhighlight>
    :at this point, you can test your knsrc file with khotnewstuff4 like so:
    :at this point, you can test your knsrc file with khotnewstuff4 like so:
    <syntaxhighlight lang="text">
    <syntaxhighlight lang="text">
    khotnewstuff4 yourdata.knsrc
    khotnewstuff4 yourdata.knsrc
    </code>
    </syntaxhighlight>
    :it should show you a download dialog of the data available on your provider(s).
    :it should show you a download dialog of the data available on your provider(s).


    Line 65: Line 65:
    <syntaxhighlight lang="text">
    <syntaxhighlight lang="text">
    static KNS::Entry::List download();
    static KNS::Entry::List download();
    </code>
    </syntaxhighlight>


    :if you use this method, your knsrc file must have the same name as your KGlobal::activeComponent().componentName(), it will create an Engine object, initialize it with the knsrc file, and call downloadDialogModal, then before returning it will copy the list of modified (installed, uninstalled, etc.) entries.  Use is like this:
    :if you use this method, your knsrc file must have the same name as your KGlobal::activeComponent().componentName(), it will create an Engine object, initialize it with the knsrc file, and call downloadDialogModal, then before returning it will copy the list of modified (installed, uninstalled, etc.) entries.  Use is like this:
    Line 80: Line 80:
         }
         }
         qDeleteAll(entries);
         qDeleteAll(entries);
    </code>
    </syntaxhighlight>
    :Taken from kdeedu/parley/src/parleydocument.cpp
    :Taken from kdeedu/parley/src/parleydocument.cpp


    Line 100: Line 100:
             }
             }
         }
         }
    </code>
    </syntaxhighlight>
    :Taken from plasma/containments/desktop/backgrounddialog.cpp
    :Taken from plasma/containments/desktop/backgrounddialog.cpp

    Revision as of 20:52, 29 June 2011

    This tutorial informs about how to use Get Hot New Stuff collaborative data sharing features in your KDE application. Complementary to this tutorial, there is a porting guide for KDE 3 developers and another tutorial in SVN. The KNS2-enabled application list is also a good reference to find similar applications.

    Terminology

    First some basic terminology just to get us all on the same page. KHotNewStuff2 is the new library that implements the GHNS freedesktop.org specification for downloading and uploading user data. It will also support DXS (Desktop Exchange Service)

    Use it in your application

    There are a many good examples for how to use khotnewstuff2 in the KDE-Edu module. Look at their source code for examples if needed, but it's basically a 2-part process to get download into your app.

    First write a .knsrc file.

    A .knsrc file is just a file telling the library which options to use for a given application. It also lists where providers can be found, where uploads should be sent, etc. Anyway, the format of the file is an ini file with one group:

    [KNewStuff2]
    ProvidersUrl=
    InstallationCommand=
    Uncompress=
    
    NOTE: InstallationCommand is optional, and if included will be invoked after each item is downloaded.
    NOTE: Uncompress is optional, and if included will try to uncompress all downloads into the target folder according to the mime-type of the file.
    • Uncompress possible values as of r794016 are
    • "always" - always attempt to uncompress (old values of "true" are seen as "always"
    • "archive" - uncompress if it's an archive but copy otherwise
    • "never" - (default) never attempt to uncompress


    One of the following is required to tell where downloads should go:
    TargetDir=
    InstallPath=
    StandardResource=
    AbsoluteInstallPath=
    
    • TargetDir installs to KStandardDirs::locateLocal("data") + TargetDir + "/"
    • StandardResource installs to KStandardDirs::locateLocal(StandardResource)
    • InstallPath installs to QDir::home().path() + "/" + InstallPath
    • AbsoluteInstallPath installs to AbsoluteInstallPath + "/"
    NOTE: AbsoluteInstallPath is not portable (/boot/grub is probably not a valid path except on linux), so should not be used in anything that is meant to run on all our platforms.
    And the following values are currently read, though not used yet:
    CustomName=
    CachePolicy=
    ChecksumPolicy=
    SignaturePolicy=
    Scope=
    
    install the file using CMake install macro like this
    install( FILES yourdata.knsrc  DESTINATION  ${CONFIG_INSTALL_DIR} )
    
    at this point, you can test your knsrc file with khotnewstuff4 like so:
    khotnewstuff4 yourdata.knsrc
    
    it should show you a download dialog of the data available on your provider(s).

    Make your application launch the KNS ui with your knsrc file.

    There are many examples of using KNS in code, kde-edu apps, kdegames apps, plasma, some kcm modules, etc. Basically there are two options at this time for invoking the download dialog.
    Option 1. Use the static call. KNewStuff::Engine has a static method
    static KNS::Entry::List download();
    
    if you use this method, your knsrc file must have the same name as your KGlobal::activeComponent().componentName(), it will create an Engine object, initialize it with the knsrc file, and call downloadDialogModal, then before returning it will copy the list of modified (installed, uninstalled, etc.) entries. Use is like this:
        KNS::Entry::List entries = KNS::Engine::download();
        // list of changed entries
        foreach(KNS::Entry* entry, entries) {
            // care only about installed ones
            if (entry->status() == KNS::Entry::Installed) {
                // do something with the installed entries
                }
            }
        }
        qDeleteAll(entries);
    
    Taken from kdeedu/parley/src/parleydocument.cpp
    NOTE: Since the Ently::List is a copy of entries from the engine that has now been deleted, you are responsible for cleanup of the allocated Entry(s).


    Option 2. Allocate your own Engine object. This method is more flexible, in that you can name your knsrc file anything you want, since you call Engine::init yourself. You also don't have to worry about deleting the EntryList that is returned, since your Engine object owns it. This method is done like so:
        KNS::Engine engine(0);
        if (engine.init("wallpaper.knsrc")) {
            KNS::Entry::List entries = engine.downloadDialogModal(this);
    
            if (entries.size() > 0) {
    	    // do something with the modified entries here if you want
    
                // such as rescaning your data folder or whatnot
                m_model->reload();
            }
        }
    
    Taken from plasma/containments/desktop/backgrounddialog.cpp