File: Mainpage.dox

package info (click to toggle)
nepomuk-widgets 4:4.13.1-1
  • links: PTS, VCS
  • 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
/*
   This file is part of the Nepomuk KDE project.
   Copyright (C) 2006-2010 Sebastian Trueg <trueg@kde.org>

   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 <http://www.gnu.org/licenses/>.
*/


/** \mainpage The Nepomuk Meta Data Library

<p><b>
Overview |
\ref hacking "Using" |
\ref examples "Examples" |
\ref page_ontology "Desktop Ontologies" |
\ref nepomuk-rcgen "Resource Generator"
</b></p>

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
- <a href="http://techbase.kde.org/Development/Tutorials#Nepomuk">The Nepomuk techbase tutorials</a>

\authors
Sebastian Trueg \<trueg@kde.org\>

\maintainers
Sebastian Trueg \<trueg@kde.org\>

\licenses
\lgpl

*/


/** \page hacking Using Nepomuk

<p><b>
\ref index "Overview" |
Using |
\ref examples "Examples" |
\ref page_ontology "Desktop Ontologies" |
\ref nepomuk-rcgen "Resource Generator"
</b></p>

\section hacking_resources Handling Resources

In general there are two ways of using Nepomuk.

-# The preferred way: use the Resource subclasses as generated from \ref page_ontology
   This is also the much simpler way since Nepomuk takes care of all type casting and
   list handling automatically.
-# Using Nepomuk2::Resource directly. This is much harder since in this case
   the type names (i.e. their URIs as defined in \ref page_ontology) have to be known.
   On the other hand it allows to use additional resource types not defined in the ontology
   and handle resources without knowing their type.

Since all resource classes are derived from Nepomuk2::Resource and only add additional methods
both ways can be used interchangeably.

Resource objects (and thus also all objects of classes derived from Resource) with the same
URI share their data. Thus, if one is changed the other one is, too.


\subsection hacking_theeasyway Using Resource Subclasses

Using Resource subclasses directly is very simple. All that is necessary to handle a
resource is to know its type and its URI (the URI can vary a lot between resource types;
The simplest example is certainly a local file: the URI is the path to the file).

To access or create meta data for a resource one simply creates an instance of the
corresponding class and passes the resource URI to its constructor.

In case of a file this would look as follows.

\code
Nepomuk2::File f( "/home/foo/bar.txt" );
\endcode

Now meta data can be read and set via the methods provided by Nepomuk2::File
such as Nepomuk2::File::setAnnotation.

Each resource class also provides a static method which returns all existing instances
of this type.
See Nepomuk2::File::allFiles for an example.

See also \ref nepomuk-rcgen


\subsection hacking_thehardway Using Resource Directly

Using the Nepomuk2::Resource class directly forces one to learn a little more about
the internals of Nepomuk. Resource provides four methods to handle the properties of a
resource (reminder: all Resource subclasses as generated from \ref page_ontology are based
one these methods):

- Nepomuk2::Resource::property
- Nepomuk2::Resource::setProperty
- Nepomuk2::Resource::removeProperty
- Nepomuk2::Resource::properties

Each property's value is represented by a Nepomuk2::Variant object which can contain
another Resource or a literal (string, int, ...) or even a list of the former two. Other than
with the Resource subclasses no automatic type conversion is performed.

In case of a property that can have multiple values (cardinality greater than 1) Nepomuk2::Resource::setProperty
has to be called with a list to set more than one (the Resource subclasses simplify this by
adding add methods in addition to the set method) and Nepomuk2::Resource::getProperty
will also return a list (in both cases encapsulated in a Variant object).

When creating a Resource object there are two cases that are dealt with differently:

- The resource does not exist yet, i.e. no information about it is stored. In this case Nepomuk
  does not know the type of the resource and will fall back to %http://www.w3.org/2000/01/rdf-schema\#Resource.
- If the resource already exists the type may be empty. It will then be read from the local meta
  data store (where it was saved before by Nepomuk automatically).

As a rule of thumb one should always define the type when creating meta data and leave it empty when
reading meta data.

When using the plain Nepomuk2::Resource class one is completely free to choose the
resource URIs, the type URIs, and the property URIs. However, to preserve compatibility with
other applications one is encouraged to stick to those define in \ref page_ontology.

\section hacking_general Nepomuk Details

Nepomuk is designed so the user (the developer of a client application) does not have to care about loading or
saving the data. All data is stored directly into the RDF storage and also read from it directly.

Although in normal operation it is sufficient to only work with Nepomuk2::Resource and
its subclasses errors might occur. This is where the Nepomuk2::ResourceManager comes
in: it provides the Nepomuk2::ResourceManager::init method which can be called manually
(the resource manager will be initialized automatically anyway) to check if the initialization was
successful and Nepomuk can be used. In addition it provides the Nepomuk2::ResourceManager::error
signal which is emitted whenever an error occurs.


See \ref examples for further examples.
*/


/** \page examples Nepomuk Examples

<p><b>
\ref index "Overview" |
\ref hacking "Using" |
Examples |
\ref page_ontology "Desktop Ontologies" |
\ref nepomuk-rcgen "Resource Generator"
</b></p>

\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<Resource> tags = f.getProperty( Soprano::Vocabulary::NAO::hasTag() ).toResourceList();
QListIterator<Resource> 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<Tag> tags = f.getTags();
QListIterator<Tag> 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<QUrl, Variant> properties = f.properties();
QHashIterator<QUrl, Variant> 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
<a href="http://api.kde.org/kdesupport-api/kdesupport-apidocs/soprano/html/soprano_devel_tools.html">onto2vocabularyclass</a>
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

<p><b>
\ref index "Overview" |
\ref hacking "Using" |
\ref examples "Examples" |
Desktop Ontologies |
\ref nepomuk-rcgen "Resource Generator"
</b></p>

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

<p><b>
\ref index "Overview" |
\ref hacking "Using" |
\ref examples "Examples" |
\ref page_ontology "Desktop Ontologies" |
Resource Generator
</b></p>

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(<sources-var>
         [FAST]
         [ONTOLOGIES] <onto-file1> [<onto-file2> ...]
         [CLASSES <classname1> [<classname2> ...]]
         [VISIBILITY <visibility-name>]
       )
\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 <visibility-name> 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