Projects/Nepomuk/QuickStart: Difference between revisions

    From KDE TechBase
    No edit summary
    No edit summary
    Line 10: Line 10:


    This page serves as a very simple overview to Nepomuk. It focuses on getting started with Nepomuk and tries not to deal with internal Nepomuk concepts. Please keep in the mind that the processes described here are targeted to the general use case. If you have a more specialized use case in mind, this might not be the best way to use the Nepomuk libraries.
    This page serves as a very simple overview to Nepomuk. It focuses on getting started with Nepomuk and tries not to deal with internal Nepomuk concepts. Please keep in the mind that the processes described here are targeted to the general use case. If you have a more specialized use case in mind, this might not be the best way to use the Nepomuk libraries.
    =Libraries and Headers=
    Most of the non graphic parts of Nepomuk are present in the NepomukCore repositories. It is shipped with KDE 4.9, and should be provided by your distribution. For simple development, it would be easier to stick with your distribution version.
    With KDE 4.9, the Nepomuk libraries moved to the Nepomuk2 namespace. The headers also follow a similar convention.
    ==Headers==
    For the example you need the following includes:
    <syntaxhighlight lang="cpp-qt">
    #include <Nepomuk2/Tag>
    #include <Nepomuk2/Resource>
    #include <Nepomuk2/File>
    #include <KDebug>
    </syntaxhighlight>
    ==CMake==
    KDE Projects generally use cmake as a build tool. Nepomuk is no different. In order to use Nepomuk you need to add the relevant macros for Nepomuk in your CMakeLists.txt
    <syntaxhighlight lang="cmake">
    find_package(NepomukCore REQUIRED)
    target_link_libraries(myfile ${NEPOMUK_CORE_LIBRARY} )
    </syntaxhighlight>


    =Basic Terminology=
    =Basic Terminology=
    Line 92: Line 116:
    rating = rating + 1;
    rating = rating + 1;
    fileRes.setRating( rating );
    fileRes.setRating( rating );
    </syntaxhighlight>
    =Includes and Linking=
    ==Headers==
    For the example you need the following includes:
    <syntaxhighlight lang="cpp-qt">
    #include <Nepomuk2/Tag>
    #include <Nepomuk2/Resource>
    #include <Nepomuk2/File>
    #include <KDebug>
    </syntaxhighlight>
    ==CMake==
    In your CMakeLists.txt, you need the find macro for Nepomuk and link to it of course ;)
    <syntaxhighlight lang="cmake">
    find_package(NepomukCore REQUIRED)
    target_link_libraries(myfile ${NEPOMUK_CORE_LIBRARY} )
    </syntaxhighlight>
    </syntaxhighlight>

    Revision as of 17:21, 1 August 2012


    Nepomuk Quickstart
    Tutorial Series   Nepomuk
    Previous   Getting started with KDE development
    What's Next   Handle Resource Metadata with Nepomuk
    Further Reading   n/a


    This page serves as a very simple overview to Nepomuk. It focuses on getting started with Nepomuk and tries not to deal with internal Nepomuk concepts. Please keep in the mind that the processes described here are targeted to the general use case. If you have a more specialized use case in mind, this might not be the best way to use the Nepomuk libraries.

    Libraries and Headers

    Most of the non graphic parts of Nepomuk are present in the NepomukCore repositories. It is shipped with KDE 4.9, and should be provided by your distribution. For simple development, it would be easier to stick with your distribution version.

    With KDE 4.9, the Nepomuk libraries moved to the Nepomuk2 namespace. The headers also follow a similar convention.

    Headers

    For the example you need the following includes:

    #include <Nepomuk2/Tag>
    #include <Nepomuk2/Resource>
    #include <Nepomuk2/File>
    #include <KDebug>
    

    CMake

    KDE Projects generally use cmake as a build tool. Nepomuk is no different. In order to use Nepomuk you need to add the relevant macros for Nepomuk in your CMakeLists.txt

    find_package(NepomukCore REQUIRED)
    target_link_libraries(myfile ${NEPOMUK_CORE_LIBRARY} )
    

    Basic Terminology

    Nepomuk is centred around a main 'Resource' class. For simple, non-high performance access to Nepomuk, it is recommended that you use the Resource class.

    Everything in Nepomuk is a Resource. Each Resource has a number of properties associated with it, which are stored as (key, value) pairs. They keys are referred to as properties or predicates, and the values are referred to as the objects.

    Every file, folder, contact or tag is a Resource.

    Dealing with Tags

    Every tag in Nepomuk is a Resource. In fact the Tag class is also derived from the Resource class.

    Setting Tags

    Nepomuk2::Tag tag( "Awesome-Tag-Name" );
    Nepomuk2::Resource res( url );
    res.addTag( tag );
    


    The 'Nepomuk2::Tag' class will automatically look for for a tag called "Awesome-Tag-Name", it is finds it then Tag::exists() will return true. Otherwise, the tag will be saved the first time the tag is used. In our case, when we add the tag to the Resource via Resource::addTag(), the tag will be saved.

    Retrieving Tags

    using namespace Nepomuk2;
    
    Resource res( url );
    QList<Tag> tags = res.tags();
    foreach(const Tag& tag, tags)
        kDebug() << tag.genericLabel();
    


    Every resource has a predefined function for retrieving all the Tags any resource is tagged with - Resource::tags(). The Resource::genericLabel() function tries to find a presentable name for any resource. In the case of tags, it returns the tags name.

    Listing all the Tags

    The simplest way to list all the tags that are present in Nepomuk is via a static function - Tag::allTags(). You, however, need to be careful using this in a production environment as it executes a blocking query in the background. Depending on the number of tags on the system, it could take some time.

    using namespace Nepomuk2;
    
    QList<Tag> tags = Tag::allTags();
    foreach(const Tag& tag, tags)
        kDebug() << tag.genericLabel();
    


    Dealing with files

    Every file in Nepomuk is represented as a resource. Since dealing with files is very common, we provide a special File class which is derived from the Resource class. We also provide convenience functions for checking if a resource is a file.

    using namespace Nepomuk2;
    
    File fileRes( urlOfTheFile );
    kDebug() << fileRes.url();
    
    Resource res( urlOfTheFile );
    if( res.isFile() )
        kDebug() << res.toFile().url();
    


    Internally Nepomuk Files are not very different from other Resources.

    Ratings

    Every resource in Nepomuk can be given a numeric rating. It is generally done on a scale of 0-10.

    using namespace Nepomuk2;
    
    File fileRes( urlOfTheFile );
    int rating = fileRes.rating();
    
    rating = rating + 1;
    fileRes.setRating( rating );