1/*
2 This file is part of the Nepomuk KDE project.
3 Copyright (C) 2010 Sebastian Trueg <trueg@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) version 3, or any
9 later version accepted by the membership of KDE e.V. (or its
10 successor approved by the membership of KDE e.V.), which shall
11 act as a proxy defined in Section 6 of version 3 of the license.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library. If not, see <http://www.gnu.org/licenses/>.
20*/
21
22#ifndef _NEPOMUK_UTILS_GLOBAL_H_
23#define _NEPOMUK_UTILS_GLOBAL_H_
24
25#include "nepomukutils_export.h"
26#include "resource.h"
27
28#include <QtCore/QFlags>
29#include <QtCore/QDateTime>
30#include <QtCore/QList>
31
32#include "kurl.h"
33
34namespace Nepomuk {
35 class Variant;
36
37 namespace Types {
38 class Property;
39 }
40
41 namespace Utils {
42 /**
43 * Flags to change the behaviour of formatPropertyValue().
44 *
45 * \since 4.6
46 */
47 enum PropertyFormatFlag {
48 /**
49 * No flags, ie. default behaviour.
50 */
51 NoPropertyFormatFlags = 0x0,
52
53 /**
54 * Include html links to %Nepomuk resources, files, and
55 * %Nepomuk queries.
56 */
57 WithKioLinks = 0x1
58 };
59 Q_DECLARE_FLAGS( PropertyFormatFlags, PropertyFormatFlag )
60
61 /**
62 * Format a property to be displayed to the user.
63 *
64 * \param property The actual property to which the value applies to.
65 * \param value The actual value to be formatted.
66 * \param flags Optional flags to change the resulting string.
67 * \param resources The resources which the property applies to. Depending on the property
68 * the user readable representation might differ based on the resources' types. Using an
69 * empty list is perfectly valid.
70 *
71 * \return A user readable representation of the value which corresponds to \p resource
72 * and \p property. This string may contain Qt-style HTML tags for links and special formatting.
73 *
74 * \since 4.6
75 */
76 NEPOMUKUTILS_EXPORT QString formatPropertyValue( const Nepomuk::Types::Property& property,
77 const Nepomuk::Variant& value,
78 const QList<Nepomuk::Resource>& resources = QList<Nepomuk::Resource>(),
79 PropertyFormatFlags flags = NoPropertyFormatFlags );
80
81 /**
82 * Save a copy event in %Nepomuk stating that \p src has been copied to \p dest
83 * with an optional download \p startTime and an optional \p referrer URL that
84 * indicates from which webpage a download was initiated.
85 *
86 * \return The download event resource. Use finishCopyEvent() to store the event's end time.
87 *
88 * \since 4.6
89 */
90 NEPOMUKUTILS_EXPORT Nepomuk::Resource createCopyEvent( const KUrl& src,
91 const KUrl& dest,
92 const QDateTime& startTime = QDateTime(),
93 const KUrl& referrer = KUrl() );
94
95 /**
96 * Save the end time of a copy event created via createCopyEvent().
97 *
98 * \param eventResource The resource returned by createCopyEvent().
99 * \param endTime The time the copy event ended to the saved.
100 *
101 * \since 4.6
102 */
103 NEPOMUKUTILS_EXPORT void finishCopyEvent( Nepomuk::Resource& eventResource, const QDateTime& endTime );
104 }
105}
106
107Q_DECLARE_OPERATORS_FOR_FLAGS( Nepomuk::Utils::PropertyFormatFlags )
108
109#endif
110