1/******************************************************************************
2* Copyright 2007 by Riccardo Iaconelli <riccardo@kde.org> *
3* *
4* This library is free software; you can redistribute it and/or *
5* modify it under the terms of the GNU Library General Public *
6* License as published by the Free Software Foundation; either *
7* version 2 of the License, or (at your option) any later version. *
8* *
9* This library is distributed in the hope that it will be useful, *
10* but WITHOUT ANY WARRANTY; without even the implied warranty of *
11* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
12* Library General Public License for more details. *
13* *
14* You should have received a copy of the GNU Library General Public License *
15* along with this library; see the file COPYING.LIB. If not, write to *
16* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, *
17* Boston, MA 02110-1301, USA. *
18*******************************************************************************/
19
20#ifndef PLASMA_PACKAGEMETADATA_H
21#define PLASMA_PACKAGEMETADATA_H
22
23#include <QtCore/QString>
24
25#include <plasma/plasma_export.h>
26
27#include <kurl.h>
28
29namespace Plasma
30{
31
32class PackageMetadataPrivate;
33
34/**
35 * @class PackageMetadata plasma/packagemetadata.h <Plasma/PackageMetadata>
36 *
37 * @short Provides metadata for a Package.
38 **/
39class PLASMA_EXPORT PackageMetadata
40{
41public:
42 /**
43 * Constructs a metadata object using the values in the file at path
44 *
45 * @param path path to a metadata.desktop file
46 **/
47 explicit PackageMetadata(const QString &path = QString());
48
49 /**
50 * Copy constructor
51 **/
52 PackageMetadata(const PackageMetadata &other);
53
54 ~PackageMetadata();
55
56 PackageMetadata &operator=(const PackageMetadata &other);
57
58 bool isValid() const;
59
60 /**
61 * Writes out the metadata to filename, which should be a .desktop
62 * file. It writes out the information in a format that is compatible
63 * with KPluginInfo
64 * @see KPluginInfo
65 *
66 * @param filename path to the file to write to
67 **/
68 void write(const QString &filename) const;
69
70 /**
71 * Reads in metadata from a file, which should be a .desktop
72 * file. It writes out the information in a format that is compatible
73 * with KPluginInfo
74 * @see KPluginInfo
75 *
76 * @param filename path to the file to write to
77 **/
78 void read(const QString &filename);
79
80 QString name() const;
81 QString description() const;
82 QStringList keywords() const;
83 QString serviceType() const;
84 QString author() const;
85 QString email() const;
86 QString version() const;
87 QString website() const;
88 QString license() const;
89 QString application() const;
90 QString category() const;
91 QString requiredVersion() const;
92 QString pluginName() const;
93 QString implementationApi() const;
94 KUrl remoteLocation() const;
95
96 QString type() const;
97
98 /**
99 * Set the name of the package used to displayed
100 * a short describing name.
101 */
102 void setName(const QString &);
103
104 /**
105 * Set the description used to provide some general
106 * information what the package is about.
107 */
108 void setDescription(const QString &);
109
110 /**
111 * Returns the icon name associated with this package, or QString() if none
112 * @since 4.5
113 */
114 QString icon() const;
115
116 /**
117 * Set the icon name to be used with this package
118 * @since 4.5
119 */
120 void setIcon(const QString &icon);
121
122 /**
123 * Set the keywords used to provide search and categorizations
124 * @param keywords the keywords to associate with this package
125 */
126 void setKeywords(const QStringList &keywords);
127
128 /**
129 * Set the service-type which defines the X-KDE-ServiceTypes
130 * type within the desktop file. If not defined this
131 * defaults to "Plasma/Applet,Plasma/Containment" in the
132 * desktop file.
133 */
134 void setServiceType(const QString &);
135
136 /**
137 * Set the name of the author of the package.
138 */
139 void setAuthor(const QString &);
140
141 /**
142 * Set the E-Mail address of the author or of the project
143 * that provided the package.
144 */
145 void setEmail(const QString &);
146
147 /**
148 * Set the version of the package.
149 */
150 void setVersion(const QString &);
151
152 /**
153 * Set the website URL where the package is hosted or
154 * where additional details about the project are available.
155 */
156 void setWebsite(const QString &);
157
158 /**
159 * Set the license the package is distributed under.
160 */
161 void setLicense(const QString &);
162
163 /**
164 * Set the name of the application this package may
165 * belongs to. This is used only for display purposes
166 * so far.
167 */
168 void setApplication(const QString &);
169
170 /**
171 * Sets the category this package belongs in
172 */
173 void setCategory(const QString &);
174
175 /**
176 * Set the required version. See also the setVersion()
177 * method.
178 */
179 void setRequiredVersion(const QString &);
180
181 /**
182 * Set the url where this package is hosted.
183 */
184 void setRemoteLocation(const KUrl &);
185
186 /**
187 * Set the type of the package. If not defined this
188 * defaults to "Service" in the desktop file.
189 */
190 void setType(const QString &type);
191
192 /**
193 * Set the plugin name of the package.
194 *
195 * The plugin name is used to locate the package;
196 * @code
197 * QString serviceName("plasma-applet-" + data.pluginName());
198 * QString service = KStandardDirs::locateLocal("services", serviceName + ".desktop");
199 * @endcode
200 */
201 void setPluginName(const QString &name);
202
203 /**
204 * Set the implementation API this package uses.
205 */
206 void setImplementationApi(const QString &api);
207
208private:
209 PackageMetadataPrivate * const d;
210};
211
212}
213#endif
214