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 * \class KNSCore::Entry
39 * \inmodule KNewStuffCore
40 *
41 * \brief KNewStuff data entry container.
42 *
43 * This class provides accessor methods to the data objects
44 * as used by KNewStuff.
45 *
46 * \br Maintainer:
47 * Jeremy Whiting (jpwhiting@kde.org)
48 */
49class KNEWSTUFFCORE_EXPORT Entry
50{
51 Q_GADGET
52public:
53 typedef QList<Entry> List;
54
55 /*!
56 * \qmlproperty string Entry::providerId
57 */
58 /*!
59 * \property KNSCore::Entry::providerId
60 */
61 Q_PROPERTY(QString providerId READ providerId)
62
63 /*!
64 * \qmlproperty string Entry::uniqueId
65 */
66 /*!
67 * \property KNSCore::Entry::uniqueId
68 */
69 Q_PROPERTY(QString uniqueId READ uniqueId)
70
71 /*!
72 * \qmlproperty string Entry::status
73 */
74 /*!
75 * \property KNSCore::Entry::status
76 */
77 Q_PROPERTY(KNSCore::Entry::Status status READ status)
78
79 /*!
80 * \qmlproperty EntryType Entry::entryType
81 */
82 /*!
83 * \property KNSCore::Entry::entryType
84 */
85 Q_PROPERTY(KNSCore::Entry::EntryType entryType READ entryType)
86
87 /*!
88 * \qmlproperty string Entry::name
89 */
90 /*!
91 * \property KNSCore::Entry::name
92 */
93 Q_PROPERTY(QString name READ name)
94
95 /*!
96 * \qmlproperty Author Entry::author
97 */
98 /*!
99 * \property KNSCore::Entry::author
100 */
101 Q_PROPERTY(KNSCore::Author author READ author)
102
103 /*!
104 * \qmlproperty string Entry::shortSummary
105 */
106 /*!
107 * \property KNSCore::Entry::shortSummary
108 */
109 Q_PROPERTY(QString shortSummary READ shortSummary)
110
111 /*!
112 * \qmlproperty string Entry::summary
113 */
114 /*!
115 * \property KNSCore::Entry::summary
116 */
117 Q_PROPERTY(QString summary READ summary)
118 // TODO Q_PROPERTY(QString previews READ previews)
119
120 /*!
121 * \qmlproperty url Entry::homepage
122 */
123 /*!
124 * \property KNSCore::Entry::homepage
125 */
126 Q_PROPERTY(QUrl homepage READ homepage)
127
128 /*!
129 * \qmlproperty string Entry::donationLink
130 */
131 /*!
132 * \property KNSCore::Entry::donationLink
133 */
134 Q_PROPERTY(QString donationLink READ donationLink)
135
136 /*!
137 * \qmlproperty int Entry::numberOfComments
138 */
139 /*!
140 * \property KNSCore::Entry::numberOfComments
141 */
142 Q_PROPERTY(int numberOfComments READ numberOfComments)
143
144 /*!
145 * \qmlproperty int Entry::rating
146 */
147 /*!
148 * \property KNSCore::Entry::rating
149 */
150 Q_PROPERTY(int rating READ rating)
151
152 /*!
153 * \qmlproperty int Entry::downloadCount
154 */
155 /*!
156 * \property KNSCore::Entry::downloadCount
157 */
158 Q_PROPERTY(int downloadCount READ downloadCount)
159
160 /*!
161 * \qmlproperty list<DownloadLinkInformation> Entry::downloadLinks
162 */
163 /*!
164 * \property KNSCore::Entry::downloadLinks
165 */
166 Q_PROPERTY(QList<KNSCore::Entry::DownloadLinkInformation> downloadLinks READ downloadLinkInformationList)
167
168 /*!
169 * \enum KNSCore::Entry::Status
170 *
171 * \brief Status of the entry.
172 *
173 * An entry will be downloadable from the provider's
174 * site prior to the download. Once downloaded and installed, it will
175 * be either installed or updateable, implying an out-of-date
176 * installation. Finally, the entry can be deleted and hence show up as
177 * downloadable again.
178 *
179 * Entries not taking part in this cycle, for example those in upload,
180 * have an invalid status.
181 *
182 * \sa setStatus
183 * \sa status
184 *
185 * \value Invalid
186 * \value Downloadable
187 * \value Installed
188 * \value Updateable
189 * \value Deleted
190 * \value Installing
191 * \value Updating
192 */
193 enum Status {
194 Invalid,
195 Downloadable,
196 Installed,
197 Updateable,
198 Deleted,
199 Installing,
200 Updating,
201 };
202 Q_ENUM(Status)
203
204 /*!
205 * \enum KNSCore::Entry::Source
206 *
207 * \brief Source of the entry.
208 *
209 * An entry's data is coming from either cache, or an online provider.
210 * This helps the engine know which data to use when merging cached entries with online
211 * entry data.
212 *
213 * \sa setSource
214 * \sa source
215 *
216 * \value Cache
217 * \value Online
218 * \value Registry
219 */
220 enum Source {
221 Cache,
222 Online,
223 Registry,
224 };
225
226 /*!
227 * \enum KNSCore::Entry::PreviewType
228 *
229 * \brief Defines the entry's preview image type.
230 *
231 * \sa previewImage
232 * \sa previewUrl
233 * \sa setPreviewImage
234 * \sa setPreviewUrl
235 *
236 * \value PreviewSmall1
237 * \value PreviewSmall2
238 * \value PreviewSmall3
239 * \value PreviewBig1
240 * \value PreviewBig2
241 * \value PreviewBig3
242 */
243 enum PreviewType {
244 PreviewSmall1,
245 PreviewSmall2,
246 PreviewSmall3,
247 PreviewBig1,
248 PreviewBig2,
249 PreviewBig3,
250 };
251
252 /*!
253 * \class KNSCore::Entry::DownloadLinkInformation
254 * \inmodule KNewStuffCore
255 *
256 * \brief Describes a download link option for an Entry.
257 *
258 * \sa appendDownloadLinkInformation
259 * \sa downloadLinkInformationList
260 */
261 struct DownloadLinkInformation {
262 /*!
263 * Displayed name.
264 */
265 QString name;
266
267 /*!
268 * Price formatted as a string.
269 */
270 QString priceAmount;
271
272 /*!
273 * OCS Distribution Type, this is for which OS the file is useful.
274 */
275 QString distributionType;
276
277 /*!
278 * Link to intermediary description.
279 */
280 QString descriptionLink;
281
282 /*!
283 * Unique integer representing the download number in the list.
284 */
285 int id;
286
287 /*!
288 * TODO
289 */
290 bool isDownloadtypeLink;
291
292 /*!
293 * Size in kilobytes.
294 */
295 quint64 size = 0;
296
297 /*!
298 * Variety of tags that can represent mimetype or url location.
299 */
300 QStringList tags;
301 };
302
303 /*!
304 * \enum KNSCore::Entry::EntryEvent
305 *
306 * \value UnknownEvent
307 * A generic event, not generally used.
308 *
309 * \value StatusChangedEvent
310 * Used when an event's status is set (use Entry::status() to get the new status).
311 *
312 * \value AdoptedEvent
313 * Used when an entry has been successfully adopted (use this to determine
314 * whether a call to Engine::adoptEntry() succeeded).
315 *
316 * \value DetailsLoadedEvent
317 * Used when more details have been added to an existing entry (such as the
318 * full description), and the UI should be updated.
319 */
320 enum EntryEvent {
321 UnknownEvent = 0,
322 StatusChangedEvent = 1,
323 AdoptedEvent = 2,
324 DetailsLoadedEvent = 3,
325 };
326 Q_ENUM(EntryEvent)
327
328 /*!
329 * \enum KNSCore::Entry::EntryType
330 *
331 * \brief Represents whether the current entry is an actual catalog entry,
332 * or an entry that represents a set of entries.
333 *
334 * \value CatalogEntry
335 * These are the main entries that KNewStuff can get the details about and
336 * download links for.
337 *
338 * \value GroupEntry
339 * These are entries whose payload is another feed. Currently only used by the OPDS provider.
340 *
341 * \since 5.83
342 */
343 enum EntryType {
344 CatalogEntry = 0,
345 GroupEntry
346 };
347 Q_ENUM(EntryType)
348
349 /*!
350 * Constructor.
351 */
352 Entry();
353
354 Entry(const Entry &other);
355 Entry &operator=(const Entry &other);
356
357 bool operator==(const Entry &other) const;
358 bool operator<(const Entry &other) const;
359
360 /*!
361 * Destructor.
362 */
363 ~Entry();
364
365 bool isValid() const;
366
367 /*!
368 * Sets the \a name for this data object.
369 */
370 void setName(const QString &name);
371
372 /*!
373 * Returns the name of the data object (potentially translated).
374 */
375 QString name() const;
376
377 /*!
378 * Set the object's unique ID. This must be unique to the provider.
379 *
380 * \a id The unique ID of this entry as unique to this provider
381 *
382 * \sa KNSCore::Provider
383 */
384 void setUniqueId(const QString &id);
385
386 /*!
387 * Get the object's unique ID. This will be unique to the provider.
388 * This is not intended as user-facing information - though it can
389 * be useful for certain purposes, this is supposed to only be used
390 * for keeping track of the entry.
391 *
392 * Returns The unique ID of this entry
393 */
394 QString uniqueId() const;
395
396 /*!
397 * Sets the data \a category, e.g. "KWin Scripts" or "Plasma Theme".
398 */
399 void setCategory(const QString &category);
400
401 /*!
402 * Returns the category of the data object. This is the category's
403 * name or ID (as opposed to displayName).
404 *
405 * \sa KNSCore::Provider::CategoryMetadata
406 * \sa KNSCore::EngineBase::categories()
407 */
408 QString category() const;
409
410 /*!
411 * Set a link to a website containing information about this entry
412 *
413 * \a page The URL representing the entry's website
414 */
415 void setHomepage(const QUrl &page);
416
417 /*!
418 * A link to a website containing information about this entry
419 *
420 * Returns The URL representing the entry's website
421 */
422 QUrl homepage() const;
423
424 /*!
425 * Sets the \a author of the object.
426 */
427 void setAuthor(const Author &author);
428
429 /*!
430 * Returns the author of the object.
431 */
432 Author author() const;
433
434 /*!
435 * Sets the \a license (abbreviation) applicable to the object.
436 */
437 void setLicense(const QString &license);
438
439 /*!
440 * Returns the license name of the object.
441 */
442 QString license() const;
443
444 /*!
445 * Sets a \a summary (which can potentially be very long)
446 */
447 void setSummary(const QString &summary);
448
449 /*!
450 * Returns a short description of what the object is all about (should be very short).
451 */
452 QString shortSummary() const;
453
454 /*!
455 * Sets a short \a summary of what the object is all about (should be very short)
456 */
457 void setShortSummary(const QString &summary);
458
459 /*!
460 * Returns a (potentially very long) description of the object.
461 */
462 QString summary() const;
463
464 /*!
465 * Sets the user written \a changelog.
466 */
467 void setChangelog(const QString &changelog);
468
469 /*!
470 * Returns the user written changelog.
471 */
472 QString changelog() const;
473
474 /*!
475 * Sets the \a version number.
476 */
477 void setVersion(const QString &version);
478
479 /*!
480 * Returns the version number string of the object.
481 */
482 QString version() const;
483
484 /*!
485 * Sets the release date to \a releasedate.
486 */
487 void setReleaseDate(const QDate &releasedate);
488
489 /*!
490 * Returns the object's release date.
491 */
492 QDate releaseDate() const;
493
494 /*!
495 * Sets the \a version number that is available as update.
496 */
497 void setUpdateVersion(const QString &version);
498
499 /*!
500 * Returns the version string of the object that is available as update.
501 */
502 QString updateVersion() const;
503
504 /*!
505 * Sets the release date that is available as update to \a releasedate.
506 */
507 void setUpdateReleaseDate(const QDate &releasedate);
508
509 /*!
510 * Returns the date of the newer version that is available as update.
511 */
512 QDate updateReleaseDate() const;
513
514 /*!
515 * Sets the object's filename to \a url.
516 */
517 void setPayload(const QString &url);
518
519 /*!
520 * Returns the object's filename.
521 */
522 QString payload() const;
523
524 /*!
525 * Sets the object's preview image file, if available.
526 *
527 * \a url is the URL of the preview image file
528 *
529 * \a type is the preview image type
530 */
531 void setPreviewUrl(const QString &url, PreviewType type = PreviewSmall1);
532
533 /*!
534 * Returns the file name of an image containing a preview of the object.
535 *
536 * \a type is the desired preview image type
537 */
538 QString previewUrl(PreviewType type = PreviewSmall1) const;
539
540 /*!
541 * Returns the entry's preview image of the specified type.
542 *
543 * \a type is the desired preview image type
544 *
545 * \note This will not be loaded automatically, instead use Engine to load the actual images.
546 */
547 QImage previewImage(PreviewType type = PreviewSmall1) const;
548
549 /*!
550 * Sets the entry's preview image for the specified preview type.
551 *
552 * \a image is the image URL
553 *
554 * \a type is the preview image type
555 *
556 */
557 void setPreviewImage(const QImage &image, PreviewType type = PreviewSmall1);
558
559 /*!
560 * Sets the files that have been installed by the install command.
561 *
562 * \a files is the list of local file names
563 *
564 */
565 void setInstalledFiles(const QStringList &files);
566
567 /*!
568 * Returns the locally installed files.
569 */
570 QStringList installedFiles() const;
571
572 /*!
573 * Returns the locally uninstalled files.
574 * \since 4.1
575 */
576 QStringList uninstalledFiles() const;
577
578 /*!
579 * Sets the \a rating between 0 (worst) and 100 (best).
580 *
581 * \internal
582 */
583 void setRating(int rating);
584
585 /*!
586 * Returns the rating for the object, which has been determined by its
587 * users and thus might change over time.
588 */
589 int rating() const;
590
591 /*!
592 * Sets the number of comments in the asset
593 *
594 * \internal
595 */
596 void setNumberOfComments(int comments);
597
598 /*!
599 * Returns the number of comments against the asset.
600 */
601 int numberOfComments() const;
602
603 /*!
604 * Sets the number of downloads.
605 *
606 * \internal
607 */
608 void setDownloadCount(int downloads);
609
610 /*!
611 * Returns the download count for the object, which has been determined
612 * by its hosting sites and thus might change over time.
613 */
614 int downloadCount() const;
615
616 /*!
617 * Returns how many people have marked themselves as fans of this entry.
618 *
619 * \sa KNSCore::EngineBase::becomeFan
620 */
621 int numberFans() const;
622
623 /*!
624 * Sets how many people are fans.
625 *
626 * \note This is purely informational. To become a fan, call the
627 * KNSCore::Engine::becomeFan function.
628 *
629 * \a fans The number of fans this entry has
630 *
631 * \sa KNSCore::EngineBase::becomeFan
632 */
633 void setNumberFans(int fans);
634
635 /*!
636 * Returns the number of entries in the knowledgebase for this entry.
637 */
638 int numberKnowledgebaseEntries() const;
639
640 /*!
641 * Sets the number of knowledgebase entries for this entry.
642 *
643 * \a num is the number of entries
644 */
645 void setNumberKnowledgebaseEntries(int num);
646
647 /*!
648 * Returns the link for the knowledgebase for this entry.
649 */
650 QString knowledgebaseLink() const;
651
652 /*!
653 * Set the link for the knowledgebase.
654 *
655 * \note This is not checked for validity, the caller must do this.
656 *
657 * \a link is the string version of the URL for the knowledgebase
658 */
659 void setKnowledgebaseLink(const QString &link);
660
661 /*!
662 * Returns the number of available download options for this entry.
663 *
664 * \sa downloadLinkInformationList
665 */
666 int downloadLinkCount() const;
667
668 /*!
669 * Returns a list of downloadable data for this entry.
670 *
671 * \sa appendDownloadLinkInformation
672 * \sa DownloadLinkInformation
673 */
674 QList<DownloadLinkInformation> downloadLinkInformationList() const;
675
676 /*!
677 * Adds a new download option to this entry.
678 *
679 * \a info is the new download option
680 *
681 * \sa clearDownloadLinkInformation
682 * \sa downloadLinkInformationList
683 */
684 void appendDownloadLinkInformation(const DownloadLinkInformation &info);
685
686 /*!
687 * Removes all download options from this entry
688 *
689 * \sa appendDownloadLinkInformation
690 * \sa downloadLinkInformationList
691 */
692 void clearDownloadLinkInformation();
693
694 /*!
695 * Returns a string representing the URL for a website where the user can donate
696 * to the author of this entry.
697 */
698 QString donationLink() const;
699
700 /*!
701 * Sets a string representation of the URL for the donation website for this entry.
702 * \note This is not checked for validity, the caller must do this.
703 *
704 * \a link is the string version of the URL for the entry's donation website
705 */
706 void setDonationLink(const QString &link);
707
708 /*!
709 * Returns the set of tags assigned specifically to this content item. This does not include
710 * tags for the download links. To get those, you must concatenate the lists yourself.
711 *
712 * \sa downloadLinkInformationList()
713 * \sa KNSCore::Entry::DownloadLinkInformation
714 * \sa EngineBase::setTagFilter
715 * \since 5.51
716 */
717 QStringList tags() const;
718
719 /*!
720 * Sets the tags for the content item.
721 *
722 * \a tags is a string list containing the tags for this entry
723 *
724 * \since 5.51
725 */
726 void setTags(const QStringList &tags);
727
728 /*!
729 * Returns the id of the provider this entry belongs to.
730 */
731 QString providerId() const;
732
733 /*!
734 * Sets the \a id of the provider this entry belongs to.
735 */
736 void setProviderId(const QString &id);
737
738 /*!
739 * Sets the \a source of this entry.
740 */
741 void setSource(Source source);
742
743 /*!
744 * Returns the source of this entry.
745 */
746 Source source() const;
747
748 /*!
749 * Sets the entry's \a type.
750 * \since 5.83
751 */
752 void setEntryType(EntryType type);
753
754 /*!
755 * Returns the entry's type.
756 */
757 EntryType entryType() const;
758
759 /*!
760 * Sets the XML for the entry.
761 *
762 * This method parses the xml and sets the private members accordingly
763 * used to deserialize data loaded from provider.
764 *
765 * \a reader defines where to read the XML string from
766 *
767 * Returns whether or not setting the values was successful
768 *
769 * \since 5.36
770 */
771 bool setEntryXML(QXmlStreamReader &reader);
772
773 /*!
774 * Sets the entry's status. If no status is set, the default will be
775 * Invalid.
776 *
777 * Note that while this enum is currently found in KNS3::Entry,
778 * it will be moved to this class once the binary compatibility
779 * lock is lifted for Frameworks 6. For now, you should read any
780 * reference to the KNS3::Entry::Status enumerator as KNSCore::Entry::Status
781 *
782 * \a status New status of the entry
783 */
784 void setStatus(KNSCore::Entry::Status status);
785
786 /*!
787 * Returns the entry's status.
788 */
789 KNSCore::Entry::Status status() const;
790
791 /// \internal
792 void setEntryDeleted();
793
794private:
795 friend class StaticXmlProvider;
796 friend class Cache;
797 friend class Cache2;
798 friend class Installation;
799 friend class AtticaProvider;
800 friend class AtticaRequester;
801 friend class Transaction;
802 friend class TransactionPrivate;
803 friend testEntry;
804 KNEWSTUFFCORE_NO_EXPORT void setEntryRequestedId(const QString &id);
805 QDomElement entryXML() const;
806 bool setEntryXML(const QDomElement &xmldata);
807 QExplicitlySharedDataPointer<EntryPrivate> d;
808};
809
810inline size_t qHash(const KNSCore::Entry &entry, size_t seed = 0)
811{
812 return qHash(key: entry.uniqueId(), seed);
813}
814
815KNEWSTUFFCORE_EXPORT QDebug operator<<(QDebug debug, const KNSCore::Entry &entry);
816}
817
818Q_DECLARE_TYPEINFO(KNSCore::Entry, Q_RELOCATABLE_TYPE);
819
820#endif
821

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