## File: Mainpage.dox

package info (click to toggle)
nepomuk-widgets 4:4.13.1-1
• area: main
• in suites: jessie, jessie-kfreebsd
• size: 908 kB
• ctags: 386
• sloc: cpp: 3,302; ansic: 13; makefile: 5; sh: 4
 file content (647 lines) | stat: -rw-r--r-- 27,012 bytes parent folder | download
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647 /* This file is part of the Nepomuk KDE project. Copyright (C) 2006-2010 Sebastian Trueg This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) version 3, or any later version accepted by the membership of KDE e.V. (or its successor approved by the membership of KDE e.V.), which shall act as a proxy defined in Section 6 of version 3 of the license. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see . */ /** \mainpage The Nepomuk Meta Data Library

Overview | \ref hacking "Using" | \ref examples "Examples" | \ref page_ontology "Desktop Ontologies" | \ref nepomuk-rcgen "Resource Generator"

This is the KDE Meta Data library (not to confuse with KFileMetaData). It consists of the following parts: \li The main resource handling centered around Nepomuk2::Resource \li The handling of ontologies via classes in the Nepomuk2::Types namespace \li The desktop Nepomuk2::Query API \li \ref nepomuk_facets \li Several utility methods and classes \section overview The General Idea Three types of meta data can be identified: -# Meta data that is stored with the data itself and is available at all times. This includes id3 tags, the number of pages in a pdf document, or even the size of a file or the subject of an email. -# Meta data that is created by the user manually like annotations or tags that are assigned to files, emails, or whatever resources. -# Meta data that can be gathered automatically by applications such as the source of a downloaded file or the email an attachment was saved from or the original when copying a file locally. Type 1 is already handled in many implementations. KDE itself includes the KMetaFileInfo classes that allow extracting this kind of meta information from files and the Strigi system even creates a searchable index of this information. Nepomuk is intended for meta data of type 2 and 3. It provides an easy way to create and read meta data for arbitrary resources (this includes for example files or emails, but also contacts or maybe even a paragraph in a pdf file). The simplest type of meta data that can be handled with Nepomuk is a comment. It is a simple string associated with a resource (a file for example). This comment is created by the user using an application that is based on Nepomuk. Nepomuk's core is designed to allow arbitrary types of meta data, i.e. any resource can be related with any other resource or value by simply naming the relation and providing the value. The power of Nepomuk, however, lies in that it provides a class for each type of resource. Each of these classes provide convenience methods to allow a simple handling of the meta data. These classes are automatically generated from a description of types and properties, i.e. an ontology (see \ref page_ontology). Nepomuk is resource based. Thus, working with Nepomuk is always done with instances representing a certain resource. This resource has a list of properties. Properties are named and have a certain type. The type can either be another resource (compare a file that was an attachment from an email) or a literal (this means for example a string, or an integer; the comment mentioned earlier would be a string literal). Each property can either have a cardinality of 1 (again a file can only be saved from one email) or greater than 1 (i.e. infinite, like one file can have arbitrary many associated comments). See \ref hacking on how Nepomuk handles literals and cardinalities greater than 1. \section toc Further Reading - \ref page_ontology - \ref hacking - \ref examples - \ref nepomuk-rcgen - The Nepomuk techbase tutorials \authors Sebastian Trueg \ \maintainers Sebastian Trueg \ \licenses \lgpl */ /** \page hacking Using Nepomuk

\ref index "Overview" | Using | \ref examples "Examples" | \ref page_ontology "Desktop Ontologies" | \ref nepomuk-rcgen "Resource Generator"

\section examples_resource Resource Handling Examples Add an annotation (a comment) to a file. \code Nepomuk2::File f( "/home/foo/bar.txt" ); f.setAnnotation( "This is just a test file that contains nothing of interest." ); \endcode The following example creates a new tag. The tag can be accessed through its name which works as an identifier. Nepomuk automatically creates a new unique URI if this tag does not already exist. \code Nepomuk2::Tag tag( "MyTag" ); Nepomuk2::File f( "/home/foo/bar.txt" ); f.addTag( tag ); \endcode Reading the information using plain Resource methods: \code Nepomuk2::Resource f( "/home/foo/bar.txt" ); QString annotation = f.getProperty( Soprano::Vocabulary::NAO::decription() ).toString(); QList tags = f.getProperty( Soprano::Vocabulary::NAO::hasTag() ).toResourceList(); QListIterator it( tags ); while( it.hasNext() ) kdDebug() << "File tagged with tag: " << it.next().genericLabel(); \endcode Reading the information using the convenience classes (be aware that these classes need to be generated from an ontology using the \ref nepomuk-rcgen "Resource Generator"): \code Nepomuk2::File f( "/home/foo/bar.txt" ); QString description = f.description(); QList tags = f.getTags(); QListIterator it( tags ); while( it.hasNext() ) kdDebug() << "File tagged with tag: " << it.next().genericLabel(); \endcode Present all defined properties of an arbitrary resource to the user including internationalized labels: \code Nepomuk2::Resource f( "/home/foo/bar.txt" ); QHash properties = f.properties(); QHashIterator it( properties ); while( it.hasNext() ) { it.next(); kdDebug() << Nepomuk2::Types::Property( it.key() ).label() << ": " << it.value().toString() << endl; } \endcode \section examples_query Query Examples Perform a simple full text query that looks for any resource containing the value 'nepomuk': \code Nepomuk2::Query::LiteralTerm nepomukTerm("nepomuk"); Nepomuk2::Query::Query query( nepomukTerm ); \endcode Create a query that lists all resources tagged with a tag whose name matches 'nepomuk': \code Nepomuk2::Query::ComparisonTerm term( Soprano::Vocabulary::NAO::hasTag(), Nepomuk2::Query::LiteralTerm("nepomuk") ); Nepomuk2::Query::Query query( term ); \endcode Create a query that lists all resources tagged with a specific tag: \code Nepomuk2::Tag tag = getFancyTag(); Nepomuk2::Query::ComparisonTerm term( Soprano::Vocabulary::NAO::hasTag(), Nepomuk2::Query::ResourceTerm( tag ) ); Nepomuk2::Query::Query query( term ); \endcode Create a query that lists all resource tagged with both the tags used above: \code Nepomuk2::Tag tag = getFancyTag(); Nepomuk2::Query::ComparisonTerm fancyTagTerm( Soprano::Vocabulary::NAO::hasTag(), Nepomuk2::Query::ResourceTerm( tag ) ); Nepomuk2::Query::ComparisonTerm nepomukTagTerm( Soprano::Vocabulary::NAO::hasTag(), Nepomuk2::Query::LiteralTerm("nepomuk") ); Nepomuk2::Query::Query query( Nepomuk2::Query::AndTerm(fancyTagTerm, nepomukTagTerm) ); \endcode Create a query that lists all \b files tagged with a specific tag: \code Nepomuk2::Tag tag = getFancyTag(); Nepomuk2::Query::ComparisonTerm term( Soprano::Vocabulary::NAO::hasTag(), Nepomuk2::Query::ResourceTerm( tag ) ); Nepomuk2::Query::FileQuery fileQuery( term ); \endcode Any other term can be used as sub term in a ComparisonTerm (%Vocabulary namespace generated via \ref nepomuk-rcgen). The following query does return all resources related to person contacts that are tagged with \p tag. \code Nepomuk2::Query::AndTerm andTerm; andTerm.addSubTerm( Nepomuk2::Query::ResourceTypeTerm( Nepomuk2::Vocabulary::NCO::PersonContact() ) ); andTerm.addSubTerm( Nepomuk2::Query::ComparisonTerm( Soprano::Vocabulary::NAO::hasTag(), Nepomuk2::Query::ResourceTerm( tag ) ) ); Nepomuk2::Query::ComparisonTerm cterm( Nepomuk2::Vocabulary::NAO::isRelated(), andTerm ); \endcode To make matters even more complex the above ComparisonTerm can be inverted: \code cterm.setInverted(true); \endcode This will not match resources related to some tagged person contact but match resources that some tagged person contact is related to (sounds confusing but remember that the properties are not symmetric by default, i.e. the graph of data is directed.) \subsection query_examples_file Listing Files Restrict the search to a specific folder: \code fileQuery.addIncludeFolder( KUrl("/home/foobar/thegoodstuff") ); \endcode Restrict the search to files-only (Vocabulary namespace generated via onto2vocabularyclass using \p ${SHAREDDESKTOPONTOLOGIES_ROOT_DIR}/nie/nfo.trig): \code Nepomuk2::Query::Term folderTerm = Nepomuk2::Query::ResourceTypeTerm( Nepomuk2::Vocabulary::NFO::Folder() ); Nepomuk2::Query::Term noFolderTerm = Nepomuk2::Query::NegationTerm::negateTerm(folderTerm); fileQuery.setTerm( Nepomuk2::Query::AndTerm( fileQuery.term(), noFolderTerm ) ); \endcode List all query results in a KDirModel: \code KDirModel* model = getFancyDirModel(); Nepomuk2::Query::Query query = buildFancyQuery(); KUrl searchUrl = query.toSearchUrl(); model->dirLister()->open( searchUrl ); \endcode KIO will use the \p nepomuksearch:/ slave to list search results as file entries. \subsection query_examples_misc Misc Query Examples Match all EmailAddress instances with a specific email address: \code Nepomuk2::Query::ComparisonTerm email( Nepomuk2::Vocabulary::NCO::emailAddress(), Soprano::LiteralValue( "trueg@kde.org" ) ); \endcode Match all nco:PersonContact instances: \code Nepomuk2::Query::ResourceTypeTerm type( Nepomuk2::Vocabulary::NCO::PersonContact() ); \endcode Match all person contacts with a specific email address: \code Nepomuk2::Query::AndTerm( type, Nepomuk2::Query::ComparisonTerm( Nepomuk2::Vocabulary::NCO::hasEmailAddress(), email ) ); \endcode */ /** \page page_ontology The Desktop Ontologies \ref index "Overview" | \ref hacking "Using" | \ref examples "Examples" | Desktop Ontologies | \ref nepomuk-rcgen "Resource Generator" The Desktop ontologies define the possible types and properties that can be used as metadata. The ontologies are based on RDF/S and NRL (The Nepomuk Representation Language which adds some OWL-like properties like cardinality or also named graphs). The types and properties can either be used directly with the Resource class or through generated classes. */ /** \page nepomuk-rcgen The Nepomuk Resource Generator \ref index "Overview" | \ref hacking "Using" | \ref examples "Examples" | \ref page_ontology "Desktop Ontologies" | Resource Generator The power of Nepomuk lies in the generated classes which allows the application developer to set and retrieve metadata according to standards without knowing any specific RDF URIs or names of properties. The idea is that the resource generator (which is installed along with the Nepomuk libraries) creates Resource subclasses that provide wrapper methods for Resource::getProperty and Resource::setProperty from ontology descriptions. \section rcgen_cmake Usage through CMake The simplest way to use the resource generator is through CMake. Nepomuk provides a macro to automatically add the class generation target. The macro is used similar to the macro for adding ui files. \code include(NepomukAddOntologyClasses) \endcode This will provide a macro called NEPOMUK_ADD_ONTOLOGY_CLASSES: \code NEPOMUK_ADD_ONTOLOGY_CLASSES( [FAST] [ONTOLOGIES] [ ...] [CLASSES [ ...]] [VISIBILITY ] ) \endcode If FAST is specified the rcgen parameter --fast will be used which results in resource classes not based on Nepomuk2::Resource but on a custom class which does not perform any checks and simply writes the data to Nepomuk (hence the name fast). The optional CLASSES parameter allows to specify the classes to be generated (RDF class names) in case one does not want all classes in the ontologies to be generated. If omitted all classes in the ontology files will be generated. The optional VISIBILITY parameter can only be used in non-fast mode and allows to set the gcc visibility to make the generated classes usable in a publically exported API. The is used to create the name of the export macro and the export include file. Thus, when using "VISIBILITY foobar" include file "foobar_export.h" needs to define FOOBAR_EXPORT. \subsection rcgen_cmake_example Example \code include(NepomukAddOntologyClasses) set(SRCS [...]) nepomuk_add_ontology_classes(SRCS ONTOLOGIES ontology.trig) kde4_add_executable(foobar${SRCS}) target_link_libraries(foobar nepomuk ) \endcode */ /** \namespace Nepomuk22::Types \brief The %Types namespace contains all classes used to handle ontology entities such as classes and properties. */ /** \namespace Nepomuk22::Vocabulary \brief The %Vocabulary namespace contains the most commonly used classes and methods used to easily access the vocabularies. If the vocabulary you are looking for is not present, it can be created using the \em onto2vocabularyclass tool provided by \em %Soprano. The best way to do that is through the provided cmake macro: \code soprano_add_ontology(my_SRC ${SHAREDDESKTOPONTOLOGIES_ROOT_DIR}/nie/nfo.trig "NFO" "Nepomuk2::Vocabulary" "trig") \endcode Here both \em %Soprano and \em SharedDesktopOntologies have been found through the cmake macros provided by the packages and kdelibs. */ /** \namespace Nepomuk22::Query \brief The %Query namespace contains all classes that make up the Nepomuk %Query API. Constructing queries consists of creating and combining different types of Term subclasses or using the QueryParser to parse user queries (see the QueryParser documentation for details on the query syntax). The constructed queries can then be executed on the nepomuk query service via the QueryServiceClient, used directly on a Soprano::Model (for example the %Nepomuk main model which can be retrieved via ResourceManager::mainModel()), or listed via KIO (see Query::Query::toSearchUrl()). \section nepomuk_constructing_queries Constructing Queries Basically all one needs to know is that each Term matches a set of resources. Different types of terms do so in different ways. The simplest type is the ResourceTerm which matches exactly one resource by URI. The ComparisonTerm matches all resources that have a property with a certain value. The LiteralTerm by itselt matches all resources that contain the string value in one of their properties, and so on. Thus, constructing a query means to combine all constraints that the results should fulfill using AndTerm and maybe OrTerm. Everything can also the nested and most importantly (this is the one real graph query thing in the API) ComparisonTerm can use any other term as object, meaning it can compare the value of a property (if it is not a literal value) to the results of a subquery. A simple example would be the following: \code // match all EmailAddress instances with a specific email address: Nepomuk2::Query::ComparisonTerm email( Nepomuk2::Vocabulary::NCO::emailAddress(), Soprano::LiteralValue( "trueg@kde.org" ) ); // match all nco:PersonContact instances Nepomuk2::Query::ResourceTypeTerm type( Nepomuk2::Vocabulary::NCO::PersonContact() ); // match all person contacts with a specific email address Nepomuk2::Query::AndTerm( type, Nepomuk2::Query::ComparisonTerm( Nepomuk2::Vocabulary::NCO::hasEmailAddress(), email ) ); \endcode \subsection nepomuk_fancy_query_operators Fancy Operators Starting with KDE SC 4.6 queries can be constructed using well known C++ operators. The above examples can now be written as: \code // match all EmailAddress instances with a specific email address: Nepomuk2::Query::ComparisonTerm email = Nepomuk2::Vocabulary::NCO::emailAddress() == Soprano::LiteralValue( "trueg@kde.org" ); // match all nco:PersonContact instances Nepomuk2::Query::ResourceTypeTerm type( Nepomuk2::Vocabulary::NCO::PersonContact() ); // match all person contacts with a specific email address Nepomuk2::Query::AndTerm = type && ( Nepomuk2::Vocabulary::NCO::hasEmailAddress() == email ); \endcode Furthermore literal comparisons can now be written as: \code Nepomuk2::Query::ComparisonTerm mtime = Nepomuk2::Vocabulary::NIE::lastModified() > Nepomuk2::Query::LiteralTerm( QDateTime::currentDateTime().addDays(-7) ); \endcode \sa \ref examples_query */ /** \namespace Nepomuk22::Utils \brief The %Utils namespace contains utility and convenience methods and classes that help the application developer with using %Nepomuk. An essential part of the %Utils is the \ref nepomuk_facets which allows developers to easily integrate a filter-based search interface into their applications. */ /** \defgroup nepomuk_facets The Facet API \brief A set of classes which allow for easy filter-based search interfaces. The Facet API which was introduced in KDE SC 4.6 provides a set of classes that allow the integration of a filter-based search interface into applications. It consists of the abstract Nepomuk2::Utils::Facet class which has to be subclassed to implement a facet of a query and a convenient GUI element Nepomuk2::Utils::FacetWidget which provides all the necessary user interaction. If Nepomuk2::Utils::FacetWidget does not suit the particular use case in an application Nepomuk2::Utils::FacetModel is provided as a more advanced approach to handling facets. If even that is too constrained one can always handle the facets manually. For convenience Nepomuk2::Utils::SimpleFacet and Nepomuk2::Utils::DynamicResourceFacet as well as a set of static factory methods in Nepomuk2::Utils::Facet are provided to make facet creation as simple as possible. \section nepomuk_facet_examples Facet Examples Nepomuk2::Utils::ProxyFacet comes with a nice feature which allows to set a condition for the facet (Nepomuk2::Utils::ProxyFacet::setFacetCondition()). The condition is a simple query term and means that the facet will not provide any choices unless the condition is met. This is best illustrated with a small example: Imagine a facet that filters on image sizes: \code Nepomuk2::Utils::SimpleFacet* imageSizeFacet = new Nepomuk2::Utils::SimpleFacet(); imageSizeFacet->addTerm( i18n("Small"), Vocabulary::NFO::width() <= Nepomuk2::Query::LiteralTerm(300)); imageSizeFacet->addTerm( i18n("Medium"), (Vocabulary::NFO::width() > Nepomuk2::Query::LiteralTerm(300)) && (Vocabulary::NFO::width() <= Nepomuk2::Query::LiteralTerm(800))); imageSizeFacet->addTerm( i18n("Large"), Vocabulary::NFO::width() > Nepomuk2::Query::LiteralTerm(800)); \endcode So far so good. However, this facet does only make sense for images. Thus, we want the choices to be hidden when the query shows other kinds of resources. What is the width of a project or an event? The solution is the facet condition: \code Nepomuk2::Utils::ProxyFacet* proxy = new Nepomuk2::Utils::ProxyFacet(); proxy->setSourceFacet(imageSizeFacet); proxy->setFacetCondition(Nepomuk2::Query::ResourceTypeTerm(Vocabulary::NFO::Image())); \endcode Now the proxy facet will only show any choices if the query contains the condition term, ie. if only images are queried. Be aware though that this feature does only work if the client uses Nepomuk2::Utils::Facet::setClientQuery(). The same approach could be used to filter a Nepomuk2::Utils::DynamicResourceFacet which filters on artists only when looking for audio files. \note The \e Vocabulary namespace can be generated via the \em onto2vocabularyclass tool provided by \em %Soprano. The best way to do that is through the provided cmake macro: \code soprano_add_ontology(my_SRC${SHAREDDESKTOPONTOLOGIES_ROOT_DIR}/nie/nfo.trig "NFO" "Nepomuk2::Vocabulary" "trig") \endcode Here both \em %Soprano and \em SharedDesktopOntologies have been found through the cmake macros provided by the packages and kdelibs. */ // DOXYGEN_SET_RECURSIVE = NO // DOXYGEN_SET_FILE_PATTERNS = *.h // DOXYGEN_SET_INPUT = @topdir@/nepomuk/Mainpage.dox // DOXYGEN_SET_INPUT += @topdir@/nepomuk/core // DOXYGEN_SET_INPUT += @topdir@/nepomuk/ui // DOXYGEN_SET_INPUT += @topdir@/nepomuk/types // DOXYGEN_SET_INPUT += @topdir@/nepomuk/query // DOXYGEN_SET_INPUT += @topdir@/nepomuk/utils // DOXYGEN_SET_EXCLUDE = @topdir@/nepomuk/core/resourcedata.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/core/nepomukmainmodel.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/core/resourcefiltermodel.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/core/nie.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/types/entitymanager.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/ui/tagcheckbox.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/ui/kblocklayout.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/utils/searchlineedit.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/utils/facetfiltermodel.h // DOXYGEN_SET_EXCLUDE += @topdir@/nepomuk/utils/facetdelegate.h // DOXYGEN_SET_EXCLUDE_PATTERNS += @topdir@/nepomuk/core/*_p.h // DOXYGEN_SET_EXCLUDE_PATTERNS += @topdir@/nepomuk/types/*_p.h // DOXYGEN_SET_EXCLUDE_PATTERNS += @topdir@/nepomuk/ui/*_p.h // DOXYGEN_SET_EXCLUDE_PATTERNS += @topdir@/nepomuk/query/*_p.h // DOXYGEN_SET_EXCLUDE_PATTERNS += @topdir@/nepomuk/utils/*_p.h // DOXYGEN_SET_PROJECT_NAME = Nepomuk // vim:ts=4:sw=4:expandtab:filetype=doxygen