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

    From KDE TechBase
    (formatting update)
    (Add some implementation examples)
    Line 7: Line 7:
    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.
    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.


    === 1. First write a .knsrc file. ===
    === 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:
    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:
    <code>
    <code>
    Line 56: Line 56:
    :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).


    === 2. Make your application launch the KNS ui with your knsrc file. ===
    === 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
    <code>
    static KNS::Entry::List download();
    </code>
     
    :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:
     
    <code>
        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);
    </code>
    :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:
     
    <code>
        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();
            }
        }
    </code>
    :Taken from plasma/containments/desktop/backgrounddialog.cpp

    Revision as of 13:31, 13 April 2008

    The page that used to be here was all KDE3 specific information, so I figured it was about time to start a new one.

    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