1/*
2 knewstuff3/entry.h.
3 SPDX-FileCopyrightText: 2002 Cornelius Schumacher <schumacher@kde.org>
4 SPDX-FileCopyrightText: 2003-2007 Josef Spillner <spillner@kde.org>
5 SPDX-FileCopyrightText: 2009 Jeremy Whiting <jpwhiting@kde.org>
6 SPDX-FileCopyrightText: 2009 Frederik Gladhorn <gladhorn@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.1-or-later
9*/
10
11#ifndef KNEWSTUFF3_ENTRY
12#define KNEWSTUFF3_ENTRY
13
14#include <QDate>
15#include <QImage>
16#include <QString>
17#include <QUrl>
18
19#include "author.h"
20#include "knewstuffcore_export.h"
21
22class testEntry;
23class QDomElement;
24class QXmlStreamReader;
25
26namespace KNSCore
27{
28static const int PreviewWidth = 96;
29static const int PreviewHeight = 72;
30class EntryPrivate;
31
32/**
33 function to remove bb code formatting that opendesktop sends
34 */
35KNEWSTUFFCORE_EXPORT QString replaceBBCode(const QString &unformattedText);
36
37/**
38 * @short KNewStuff data entry container.
39 *
40 * This class provides accessor methods to the data objects
41 * as used by KNewStuff.
42 *
43 * @author Cornelius Schumacher (schumacher@kde.org)
44 * \par Maintainer:
45 * Jeremy Whiting (jpwhiting@kde.org)
46 */
47class KNEWSTUFFCORE_EXPORT Entry
48{
49 Q_GADGET
50public:
51 typedef QList<Entry> List;
52 Q_PROPERTY(QString providerId READ providerId)
53 Q_PROPERTY(QString uniqueId READ uniqueId)
54 Q_PROPERTY(KNSCore::Entry::Status status READ status)
55 Q_PROPERTY(KNSCore::Entry::EntryType entryType READ entryType)
56
57 Q_PROPERTY(QString name READ name)
58 Q_PROPERTY(KNSCore::Author author READ author)
59 Q_PROPERTY(QString shortSummary READ shortSummary)
60 Q_PROPERTY(QString summary READ summary)
61 // TODO Q_PROPERTY(QString previews READ previews)
62 Q_PROPERTY(QUrl homepage READ homepage)
63 Q_PROPERTY(QString donationLink READ donationLink)
64 Q_PROPERTY(int numberOfComments READ numberOfComments)
65 Q_PROPERTY(int rating READ rating)
66 Q_PROPERTY(int downloadCount READ downloadCount)
67 Q_PROPERTY(QList<KNSCore::Entry::DownloadLinkInformation> downloadLinks READ downloadLinkInformationList)
68
69 /**
70 * Status of the entry. An entry will be downloadable from the provider's
71 * site prior to the download. Once downloaded and installed, it will
72 * be either installed or updateable, implying an out-of-date
73 * installation. Finally, the entry can be deleted and hence show up as
74 * downloadable again.
75 * Entries not taking part in this cycle, for example those in upload,
76 * have an invalid status.
77 */
78 enum Status {
79 Invalid,
80 Downloadable,
81 Installed,
82 Updateable,
83 Deleted,
84 Installing,
85 Updating,
86 };
87 Q_ENUM(Status)
88
89 /**
90 * Source of the entry, A entry's data is coming from either cache, or an online provider
91 * this helps the engine know which data to use when merging cached entries with online
92 * entry data
93 */
94 enum Source {
95 Cache,
96 Online,
97 Registry,
98 };
99
100 enum PreviewType {
101 PreviewSmall1,
102 PreviewSmall2,
103 PreviewSmall3,
104 PreviewBig1,
105 PreviewBig2,
106 PreviewBig3,
107 };
108
109 struct DownloadLinkInformation {
110 QString name; // Displayed name.
111 QString priceAmount; // Price formatted as a string.
112 QString distributionType; // OCS Distribution Type, this is for which OS the file is useful.
113 QString descriptionLink; // Link to intermediary description.
114 int id; // Unique integer representing the download number in the list.
115 bool isDownloadtypeLink;
116 quint64 size = 0; // Size in kilobytes.
117 QStringList tags; // variety of tags that can represent mimetype or url location.
118 };
119
120 enum EntryEvent {
121 UnknownEvent = 0, ///< A generic event, not generally used
122 StatusChangedEvent = 1, ///< Used when an event's status is set (use Entry::status() to get the new status)
123 AdoptedEvent = 2, ///< Used when an entry has been successfully adopted (use this to determine whether a call to Engine::adoptEntry() succeeded)
124 DetailsLoadedEvent = 3, ///< Used when more details have been added to an existing entry (such as the full description), and the UI should be updated
125 };
126 Q_ENUM(EntryEvent)
127
128 /**
129 * Represents whether the current entry is an actual catalog entry,
130 * or an entry that represents a set of entries.
131 * @since 5.83
132 */
133 enum EntryType {
134 CatalogEntry = 0, ///< These are the main entries that KNewStuff can get the details about and download links for.
135 GroupEntry ///< these are entries whose payload is another feed. Currently only used by the OPDS provider.
136 };
137 Q_ENUM(EntryType)
138
139 /**
140 * Constructor.
141 */
142 Entry();
143
144 Entry(const Entry &other);
145 Entry &operator=(const Entry &other);
146
147 bool operator==(const Entry &other) const;
148 bool operator<(const Entry &other) const;
149
150 /**
151 * Destructor.
152 */
153 ~Entry();
154
155 bool isValid() const;
156
157 /**
158 * Sets the name for this data object.
159 */
160 void setName(const QString &name);
161
162 /**
163 * Retrieve the name of the data object.
164 *
165 * @return object name (potentially translated)
166 */
167 QString name() const;
168
169 /**
170 * Set the object's unique ID. This must be unique to the provider.
171 *
172 * @param id The unique ID of this entry as unique to this provider
173 * @see KNSCore::Provider
174 */
175 void setUniqueId(const QString &id);
176 /**
177 * Get the object's unique ID. This will be unique to the provider.
178 * This is not intended as user-facing information - though it can
179 * be useful for certain purposes, this is supposed to only be used
180 * for keeping track of the entry.
181 *
182 * @return The unique ID of this entry
183 */
184 QString uniqueId() const;
185
186 /**
187 * Sets the data category, e.g. "KWin Scripts" or "Plasma Theme".
188 */
189 void setCategory(const QString &category);
190
191 /**
192 * Retrieve the category of the data object. This is the category's
193 * name or ID (as opposed to displayName).
194 *
195 * @see KNSCore::Provider::CategoryMetadata
196 * @see KNSCore::Engine::categories()
197 * @return object category
198 */
199 QString category() const;
200
201 /**
202 * Set a link to a website containing information about this entry
203 *
204 * @param page The URL representing the entry's website
205 */
206 void setHomepage(const QUrl &page);
207 /**
208 * A link to a website containing information about this entry
209 *
210 * @return The URL representing the entry's website
211 */
212 QUrl homepage() const;
213
214 /**
215 * Sets the author of the object.
216 */
217 void setAuthor(const Author &author);
218
219 /**
220 * Retrieve the author of the object.
221 *
222 * @return object author
223 */
224 Author author() const;
225
226 /**
227 * Sets the license (abbreviation) applicable to the object.
228 */
229 void setLicense(const QString &license);
230
231 /**
232 * Retrieve the license name of the object.
233 *
234 * @return object license
235 */
236 QString license() const;
237
238 /**
239 * Sets a description (which can potentially be very long)
240 */
241 void setSummary(const QString &summary);
242
243 /**
244 * Retrieve a short description of what the object is all about (should be very short)
245 *
246 * @return object license
247 */
248 QString shortSummary() const;
249
250 /**
251 * Sets a short description of what the object is all about (should be very short)
252 */
253 void setShortSummary(const QString &summary);
254
255 /**
256 * Retrieve a (potentially very long) description of the object.
257 *
258 * @return object description
259 */
260 QString summary() const;
261
262 /**
263 * The user written changelog
264 */
265 void setChangelog(const QString &changelog);
266 QString changelog() const;
267
268 /**
269 * Sets the version number.
270 */
271 void setVersion(const QString &version);
272
273 /**
274 * Retrieve the version string of the object.
275 *
276 * @return object version
277 */
278 QString version() const;
279
280 /**
281 * Sets the release date.
282 */
283 void setReleaseDate(const QDate &releasedate);
284
285 /**
286 * Retrieve the date of the object's publication.
287 *
288 * @return object release date
289 */
290 QDate releaseDate() const;
291
292 /**
293 * Sets the version number that is available as update.
294 */
295 void setUpdateVersion(const QString &version);
296
297 /**
298 * Retrieve the version string of the object that is available as update.
299 *
300 * @return object version
301 */
302 QString updateVersion() const;
303
304 /**
305 * Sets the release date that is available as update.
306 */
307 void setUpdateReleaseDate(const QDate &releasedate);
308
309 /**
310 * Retrieve the date of the newer version that is available as update.
311 *
312 * @return object release date
313 */
314 QDate updateReleaseDate() const;
315
316 /**
317 * Sets the object's file.
318 */
319 void setPayload(const QString &url);
320
321 /**
322 * Retrieve the file name of the object.
323 *
324 * @return object filename
325 */
326 QString payload() const;
327
328 /**
329 * Sets the object's preview file, if available. This should be a
330 * picture file.
331 */
332 void setPreviewUrl(const QString &url, PreviewType type = PreviewSmall1);
333
334 /**
335 * Retrieve the file name of an image containing a preview of the object.
336 *
337 * @return object preview filename
338 */
339 QString previewUrl(PreviewType type = PreviewSmall1) const;
340
341 /**
342 * This will not be loaded automatically, instead use Engine to load the actual images.
343 */
344 QImage previewImage(PreviewType type = PreviewSmall1) const;
345 void setPreviewImage(const QImage &image, PreviewType type = PreviewSmall1);
346
347 /**
348 * Set the files that have been installed by the install command.
349 * @param files local file names
350 */
351 void setInstalledFiles(const QStringList &files);
352
353 /**
354 * Retrieve the locally installed files.
355 * @return file names
356 */
357 QStringList installedFiles() const;
358
359 /**
360 * Retrieve the locally uninstalled files.
361 * @return file names
362 * @since 4.1
363 */
364 QStringList uninstalledFiles() const;
365
366 /**
367 * Sets the rating between 0 (worst) and 100 (best).
368 *
369 * @internal
370 */
371 void setRating(int rating);
372
373 /**
374 * Retrieve the rating for the object, which has been determined by its
375 * users and thus might change over time.
376 *
377 * @return object rating
378 */
379 int rating() const;
380
381 /**
382 * Sets the number of comments in the asset
383 *
384 * @internal
385 */
386 void setNumberOfComments(int comments);
387
388 /**
389 * @returns the number of comments against the asset
390 */
391 int numberOfComments() const;
392
393 /**
394 * Sets the number of downloads.
395 *
396 * @internal
397 */
398 void setDownloadCount(int downloads);
399
400 /**
401 * Retrieve the download count for the object, which has been determined
402 * by its hosting sites and thus might change over time.
403 *
404 * @return object download count
405 */
406 int downloadCount() const;
407
408 /**
409 * How many people have marked themselves as fans of this entry
410 *
411 * @return The number of fans this entry has
412 * @see KNSCore::Engine::becomeFan(const Entry& entry)
413 */
414 int numberFans() const;
415 /**
416 * Sets how many people are fans.
417 * Note: This is purely informational. To become a fan, call the
418 * KNSCore::Engine::becomeFan function.
419 *
420 * @param fans The number of fans this entry has
421 * @see KNSCore::Engine::becomeFan(const Entry& entry)
422 */
423 void setNumberFans(int fans);
424
425 /**
426 * The number of entries in the knowledgebase for this entry
427 * @return The number of knowledgebase entries
428 */
429 int numberKnowledgebaseEntries() const;
430 /**
431 * Set the number of knowledgebase entries for this entry
432 * @param num The number of entries
433 */
434 void setNumberKnowledgebaseEntries(int num);
435 /**
436 * The link for the knowledgebase for this entry.
437 * @return A string version of the URL for the knowledgebase
438 */
439 QString knowledgebaseLink() const;
440 /**
441 * Set the link for the knowledgebase.
442 * Note: This is not checked for validity, the caller must do this.
443 * @param link The string version of the URL for the knowledgebase
444 */
445 void setKnowledgebaseLink(const QString &link);
446
447 /**
448 * The number of available download options for this entry
449 * @return The number of download options
450 */
451 int downloadLinkCount() const;
452 /**
453 * A list of downloadable data for this entry
454 * @return The list of download options
455 * @see DownloadLinkInformation
456 */
457 QList<DownloadLinkInformation> downloadLinkInformationList() const;
458 /**
459 * Add a new download option to this entry
460 * @param info The new download option
461 */
462 void appendDownloadLinkInformation(const DownloadLinkInformation &info);
463 /**
464 * Remove all download options from this entry
465 */
466 void clearDownloadLinkInformation();
467
468 /**
469 * A string representing the URL for a website where the user can donate
470 * to the author of this entry
471 * @return The string version of the URL for the entry's donation website
472 */
473 QString donationLink() const;
474 /**
475 * Set a string representation of the URL for the donation website for this entry.
476 * Note: This is not checked for validity, the caller must do this.
477 * @param link String version of the URL for the entry's donation website
478 */
479 void setDonationLink(const QString &link);
480
481 /**
482 * The set of tags assigned specifically to this content item. This does not include
483 * tags for the download links. To get those, you must concatenate the lists yourself.
484 * @see downloadLinkInformationList()
485 * @see DownloadLinkInformation
486 * @see Engine::setTagFilter(QStringList)
487 * @since 5.51
488 */
489 QStringList tags() const;
490 /**
491 * Set the tags for the content item.
492 * @param tags A string list containing the tags for this entry
493 * @since 5.51
494 */
495 void setTags(const QStringList &tags);
496
497 /**
498 The id of the provider this entry belongs to
499 */
500 QString providerId() const;
501 void setProviderId(const QString &id);
502
503 /**
504 The source of this entry can be Cache, Registry or Online - @see source
505 */
506 void setSource(Source source);
507 Source source() const;
508
509 /**
510 * The entry type is either catalog entry, or group entry.
511 * @since 5.83
512 */
513 void setEntryType(EntryType type);
514 EntryType entryType() const;
515
516 /**
517 * set the xml for the entry
518 * parses the xml and sets the private members accordingly
519 * used to deserialize data loaded from provider
520 *
521 * @param xmldata string to load xml data from
522 *
523 * @returns whether or not setting the values was successful
524 *
525 * @since 5.36
526 */
527 bool setEntryXML(QXmlStreamReader &reader);
528
529 /**
530 * Sets the entry's status. If no status is set, the default will be
531 * \ref Invalid.
532 *
533 * Note that while this enum is currently found in KNS3::Entry,
534 * it will be moved to this class once the binary compatibility
535 * lock is lifted for Frameworks 6. For now, you should read any
536 * reference to the KNS3::Entry::Status enumerator as KNSCore::Entry::Status
537 *
538 * @param status New status of the entry
539 */
540 void setStatus(KNSCore::Entry::Status status);
541
542 /**
543 * Retrieves the entry's status.
544 *
545 * @return Current status of the entry
546 */
547 KNSCore::Entry::Status status() const;
548
549 /// @internal
550 void setEntryDeleted();
551
552private:
553 friend class StaticXmlProvider;
554 friend class Cache;
555 friend class Installation;
556 friend class AtticaProvider;
557 friend testEntry;
558 KNEWSTUFFCORE_NO_EXPORT void setEntryRequestedId(const QString &id);
559 QDomElement entryXML() const;
560 bool setEntryXML(const QDomElement &xmldata);
561 QExplicitlySharedDataPointer<EntryPrivate> d;
562};
563
564inline size_t qHash(const KNSCore::Entry &entry, size_t seed = 0)
565{
566 return qHash(key: entry.uniqueId(), seed);
567}
568
569KNEWSTUFFCORE_EXPORT QDebug operator<<(QDebug debug, const KNSCore::Entry &entry);
570}
571
572Q_DECLARE_TYPEINFO(KNSCore::Entry, Q_RELOCATABLE_TYPE);
573
574#endif
575

source code of knewstuff/src/core/entry.h