File indexing completed on 2024-04-28 11:43:33
0001 /* 0002 knewstuff3/entry.h. 0003 SPDX-FileCopyrightText: 2002 Cornelius Schumacher <schumacher@kde.org> 0004 SPDX-FileCopyrightText: 2003-2007 Josef Spillner <spillner@kde.org> 0005 SPDX-FileCopyrightText: 2009 Jeremy Whiting <jpwhiting@kde.org> 0006 SPDX-FileCopyrightText: 2009 Frederik Gladhorn <gladhorn@kde.org> 0007 0008 SPDX-License-Identifier: LGPL-2.1-or-later 0009 */ 0010 0011 #ifndef KNEWSTUFF3_ENTRYINTERNAL_P_H 0012 #define KNEWSTUFF3_ENTRYINTERNAL_P_H 0013 0014 #include <QDate> 0015 #include <QDomElement> 0016 #include <QImage> 0017 #include <QString> 0018 #include <QUrl> 0019 0020 #include "author.h" 0021 // This include only exists for the KNS3::Entry::Status enum 0022 // TODO Move the KNS3::Entry::Status enum to Core for KF6 0023 #include "KNS3/Entry" 0024 0025 #include "knewstuffcore_export.h" 0026 0027 #include <memory> 0028 0029 class QXmlStreamReader; 0030 0031 namespace KNSCore 0032 { 0033 static const int PreviewWidth = 96; 0034 static const int PreviewHeight = 72; 0035 class EntryInternalPrivate; 0036 0037 /** 0038 function to remove bb code formatting that opendesktop sends 0039 */ 0040 KNEWSTUFFCORE_EXPORT QString replaceBBCode(const QString &unformattedText); 0041 0042 /** 0043 * @short KNewStuff data entry container. 0044 * 0045 * This class provides accessor methods to the data objects 0046 * as used by KNewStuff. 0047 * 0048 * @author Cornelius Schumacher (schumacher@kde.org) 0049 * \par Maintainer: 0050 * Jeremy Whiting (jpwhiting@kde.org) 0051 */ 0052 class KNEWSTUFFCORE_EXPORT EntryInternal 0053 { 0054 Q_GADGET 0055 public: 0056 typedef QList<EntryInternal> List; 0057 0058 /** 0059 * Source of the entry, A entry's data is coming from either cache, or an online provider 0060 * this helps the engine know which data to use when merging cached entries with online 0061 * entry data 0062 */ 0063 enum Source { 0064 Cache, 0065 Online, 0066 Registry, 0067 }; 0068 0069 enum PreviewType { 0070 PreviewSmall1, 0071 PreviewSmall2, 0072 PreviewSmall3, 0073 PreviewBig1, 0074 PreviewBig2, 0075 PreviewBig3, 0076 }; 0077 0078 struct DownloadLinkInformation { 0079 QString name; // Displayed name. 0080 QString priceAmount; // Price formatted as a string. 0081 QString distributionType; // OCS Distribution Type, this is for which OS the file is useful. 0082 QString descriptionLink; // Link to intermediary description. 0083 int id; // Unique integer representing the download number in the list. 0084 bool isDownloadtypeLink; 0085 quint64 size = 0; // Size in kilobytes. 0086 QStringList tags; // variety of tags that can represent mimetype or url location. 0087 }; 0088 0089 enum EntryEvent { 0090 UnknownEvent = 0, ///< A generic event, not generally used 0091 StatusChangedEvent = 1, ///< Used when an event's status is set (use EntryInternal::status() to get the new status) 0092 AdoptedEvent = 2, ///< Used when an entry has been successfully adopted (use this to determine whether a call to Engine::adoptEntry() succeeded) 0093 DetailsLoadedEvent = 3, ///< Used when more details have been added to an existing entry (such as the full description), and the UI should be updated 0094 }; 0095 Q_ENUM(EntryEvent) 0096 0097 /** 0098 * Represents whether the current entry is an actual catalog entry, 0099 * or an entry that represents a set of entries. 0100 * @since 5.83 0101 */ 0102 enum EntryType { 0103 CatalogEntry = 0, ///< These are the main entries that KNewStuff can get the details about and download links for. 0104 GroupEntry ///< these are entries whose payload is another feed. Currently only used by the OPDS provider. 0105 }; 0106 0107 /** 0108 * Constructor. 0109 */ 0110 EntryInternal(); 0111 0112 EntryInternal(const EntryInternal &other); 0113 EntryInternal &operator=(const EntryInternal &other); 0114 0115 bool operator==(const EntryInternal &other) const; 0116 bool operator<(const EntryInternal &other) const; 0117 0118 /** 0119 * Destructor. 0120 */ 0121 ~EntryInternal(); 0122 0123 bool isValid() const; 0124 0125 /** 0126 * Sets the name for this data object. 0127 */ 0128 void setName(const QString &name); 0129 0130 /** 0131 * Retrieve the name of the data object. 0132 * 0133 * @return object name (potentially translated) 0134 */ 0135 QString name() const; 0136 0137 /** 0138 * Set the object's unique ID. This must be unique to the provider. 0139 * 0140 * @param id The unique ID of this entry as unique to this provider 0141 * @see KNSCore::Provider 0142 */ 0143 void setUniqueId(const QString &id); 0144 /** 0145 * Get the object's unique ID. This will be unique to the provider. 0146 * This is not intended as user-facing information - though it can 0147 * be useful for certain purposes, this is supposed to only be used 0148 * for keeping track of the entry. 0149 * 0150 * @return The unique ID of this entry 0151 */ 0152 QString uniqueId() const; 0153 0154 /** 0155 * Sets the data category, e.g. "KWin Scripts" or "Plasma Theme". 0156 */ 0157 void setCategory(const QString &category); 0158 0159 /** 0160 * Retrieve the category of the data object. This is the category's 0161 * name or ID (as opposed to displayName). 0162 * 0163 * @see KNSCore::Provider::CategoryMetadata 0164 * @see KNSCore::Engine::categories() 0165 * @return object category 0166 */ 0167 QString category() const; 0168 0169 /** 0170 * Set a link to a website containing information about this entry 0171 * 0172 * @param page The URL representing the entry's website 0173 */ 0174 void setHomepage(const QUrl &page); 0175 /** 0176 * A link to a website containing information about this entry 0177 * 0178 * @return The URL representing the entry's website 0179 */ 0180 QUrl homepage() const; 0181 0182 /** 0183 * Sets the author of the object. 0184 */ 0185 void setAuthor(const Author &author); 0186 0187 /** 0188 * Retrieve the author of the object. 0189 * 0190 * @return object author 0191 */ 0192 Author author() const; 0193 0194 /** 0195 * Sets the license (abbreviation) applicable to the object. 0196 */ 0197 void setLicense(const QString &license); 0198 0199 /** 0200 * Retrieve the license name of the object. 0201 * 0202 * @return object license 0203 */ 0204 QString license() const; 0205 0206 /** 0207 * Sets a description (which can potentially be very long) 0208 */ 0209 void setSummary(const QString &summary); 0210 0211 /** 0212 * Retrieve a short description of what the object is all about (should be very short) 0213 * 0214 * @return object license 0215 */ 0216 QString shortSummary() const; 0217 0218 /** 0219 * Sets a short description of what the object is all about (should be very short) 0220 */ 0221 void setShortSummary(const QString &summary); 0222 0223 /** 0224 * Retrieve a (potentially very long) description of the object. 0225 * 0226 * @return object description 0227 */ 0228 QString summary() const; 0229 0230 /** 0231 * The user written changelog 0232 */ 0233 void setChangelog(const QString &changelog); 0234 QString changelog() const; 0235 0236 /** 0237 * Sets the version number. 0238 */ 0239 void setVersion(const QString &version); 0240 0241 /** 0242 * Retrieve the version string of the object. 0243 * 0244 * @return object version 0245 */ 0246 QString version() const; 0247 0248 /** 0249 * Sets the release date. 0250 */ 0251 void setReleaseDate(const QDate &releasedate); 0252 0253 /** 0254 * Retrieve the date of the object's publication. 0255 * 0256 * @return object release date 0257 */ 0258 QDate releaseDate() const; 0259 0260 /** 0261 * Sets the version number that is available as update. 0262 */ 0263 void setUpdateVersion(const QString &version); 0264 0265 /** 0266 * Retrieve the version string of the object that is available as update. 0267 * 0268 * @return object version 0269 */ 0270 QString updateVersion() const; 0271 0272 /** 0273 * Sets the release date that is available as update. 0274 */ 0275 void setUpdateReleaseDate(const QDate &releasedate); 0276 0277 /** 0278 * Retrieve the date of the newer version that is available as update. 0279 * 0280 * @return object release date 0281 */ 0282 QDate updateReleaseDate() const; 0283 0284 /** 0285 * Sets the object's file. 0286 */ 0287 void setPayload(const QString &url); 0288 0289 /** 0290 * Retrieve the file name of the object. 0291 * 0292 * @return object filename 0293 */ 0294 QString payload() const; 0295 0296 /** 0297 * Sets the object's preview file, if available. This should be a 0298 * picture file. 0299 */ 0300 void setPreviewUrl(const QString &url, PreviewType type = PreviewSmall1); 0301 0302 /** 0303 * Retrieve the file name of an image containing a preview of the object. 0304 * 0305 * @return object preview filename 0306 */ 0307 QString previewUrl(PreviewType type = PreviewSmall1) const; 0308 0309 /** 0310 * This will not be loaded automatically, instead use Engine to load the actual images. 0311 */ 0312 QImage previewImage(PreviewType type = PreviewSmall1) const; 0313 void setPreviewImage(const QImage &image, PreviewType type = PreviewSmall1); 0314 0315 /** 0316 * Set the files that have been installed by the install command. 0317 * @param files local file names 0318 */ 0319 void setInstalledFiles(const QStringList &files); 0320 0321 /** 0322 * Retrieve the locally installed files. 0323 * @return file names 0324 */ 0325 QStringList installedFiles() const; 0326 0327 /** 0328 * Set the files that have been uninstalled by the uninstall command. 0329 * @param files local file names 0330 * @since 4.1 0331 */ 0332 void setUnInstalledFiles(const QStringList &files); 0333 0334 /** 0335 * Retrieve the locally uninstalled files. 0336 * @return file names 0337 * @since 4.1 0338 */ 0339 QStringList uninstalledFiles() const; 0340 0341 /** 0342 * Sets the rating between 0 (worst) and 100 (best). 0343 * 0344 * @internal 0345 */ 0346 void setRating(int rating); 0347 0348 /** 0349 * Retrieve the rating for the object, which has been determined by its 0350 * users and thus might change over time. 0351 * 0352 * @return object rating 0353 */ 0354 int rating() const; 0355 0356 /** 0357 * Sets the number of comments in the asset 0358 * 0359 * @internal 0360 */ 0361 void setNumberOfComments(int comments); 0362 0363 /** 0364 * @returns the number of comments against the asset 0365 */ 0366 int numberOfComments() const; 0367 0368 /** 0369 * Sets the number of downloads. 0370 * 0371 * @internal 0372 */ 0373 void setDownloadCount(int downloads); 0374 0375 /** 0376 * Retrieve the download count for the object, which has been determined 0377 * by its hosting sites and thus might change over time. 0378 * 0379 * @return object download count 0380 */ 0381 int downloadCount() const; 0382 0383 /** 0384 * How many people have marked themselves as fans of this entry 0385 * 0386 * @return The number of fans this entry has 0387 * @see KNSCore::Engine::becomeFan(const EntryInternal& entry) 0388 */ 0389 int numberFans() const; 0390 /** 0391 * Sets how many people are fans. 0392 * Note: This is purely informational. To become a fan, call the 0393 * KNSCore::Engine::becomeFan function. 0394 * 0395 * @param fans The number of fans this entry has 0396 * @see KNSCore::Engine::becomeFan(const EntryInternal& entry) 0397 */ 0398 void setNumberFans(int fans); 0399 0400 /** 0401 * The number of entries in the knowledgebase for this entry 0402 * @return The number of knowledgebase entries 0403 */ 0404 int numberKnowledgebaseEntries() const; 0405 /** 0406 * Set the number of knowledgebase entries for this entry 0407 * @param num The number of entries 0408 */ 0409 void setNumberKnowledgebaseEntries(int num); 0410 /** 0411 * The link for the knowledgebase for this entry. 0412 * @return A string version of the URL for the knowledgebase 0413 */ 0414 QString knowledgebaseLink() const; 0415 /** 0416 * Set the link for the knowledgebase. 0417 * Note: This is not checked for validity, the caller must do this. 0418 * @param link The string version of the URL for the knowledgebase 0419 */ 0420 void setKnowledgebaseLink(const QString &link); 0421 0422 /** 0423 * The number of available download options for this entry 0424 * @return The number of download options 0425 */ 0426 int downloadLinkCount() const; 0427 /** 0428 * A list of downloadable data for this entry 0429 * @return The list of download options 0430 * @see DownloadLinkInformation 0431 */ 0432 QList<DownloadLinkInformation> downloadLinkInformationList() const; 0433 /** 0434 * Add a new download option to this entry 0435 * @param info The new download option 0436 */ 0437 void appendDownloadLinkInformation(const DownloadLinkInformation &info); 0438 /** 0439 * Remove all download options from this entry 0440 */ 0441 void clearDownloadLinkInformation(); 0442 0443 /** 0444 * A string representing the URL for a website where the user can donate 0445 * to the author of this entry 0446 * @return The string version of the URL for the entry's donation website 0447 */ 0448 QString donationLink() const; 0449 /** 0450 * Set a string representation of the URL for the donation website for this entry. 0451 * Note: This is not checked for validity, the caller must do this. 0452 * @param link String version of the URL for the entry's donation website 0453 */ 0454 void setDonationLink(const QString &link); 0455 0456 /** 0457 * The set of tags assigned specifically to this content item. This does not include 0458 * tags for the download links. To get those, you must concatenate the lists yourself. 0459 * @see downloadLinkInformationList() 0460 * @see DownloadLinkInformation 0461 * @see Engine::setTagFilter(QStringList) 0462 * @since 5.51 0463 */ 0464 QStringList tags() const; 0465 /** 0466 * Set the tags for the content item. 0467 * @param tags A string list containing the tags for this entry 0468 * @since 5.51 0469 */ 0470 void setTags(const QStringList &tags); 0471 0472 /** 0473 The id of the provider this entry belongs to 0474 */ 0475 QString providerId() const; 0476 void setProviderId(const QString &id); 0477 0478 /** 0479 The source of this entry can be Cache, Registry or Online - @see source 0480 */ 0481 void setSource(Source source); 0482 Source source() const; 0483 0484 /** 0485 * The entry type is either catalog entry, or group entry. 0486 * @since 5.83 0487 */ 0488 void setEntryType(EntryType type); 0489 EntryType entryType() const; 0490 0491 /** 0492 * set the xml for the entry 0493 * parses the xml and sets the private members accordingly 0494 * used to deserialize data loaded from provider 0495 * 0496 * @param xmldata string to load xml data from 0497 * 0498 * @returns whether or not setting the values was successful 0499 * 0500 * @since 5.36 0501 */ 0502 bool setEntryXML(QXmlStreamReader &reader); 0503 0504 //#if KNEWSTUFFCORE_ENABLE_DEPRECATED_SINCE(5, 36) // TODO This is still internally used and has not been fully ported 0505 /** 0506 * set the xml for the entry 0507 * parses the xml and sets the private members accordingly 0508 * used to deserialize data loaded from provider 0509 * 0510 * @param xmldata string to load xml data from 0511 * 0512 * @returns whether or not setting the values was successful 0513 * 0514 * @deprecated since 5.36, use setEntryXML(QXmlStreamReader&) instead 0515 */ 0516 KNEWSTUFFCORE_DEPRECATED_VERSION(5, 36, "Use EntryInternal::setEntryXML(QXmlStreamReader &)") 0517 bool setEntryXML(const QDomElement &xmldata); 0518 //#endif 0519 0520 /** 0521 * get the xml string for the entry 0522 */ 0523 QDomElement entryXML() const; 0524 0525 /** 0526 * Sets the entry's status. If no status is set, the default will be 0527 * \ref Invalid. 0528 * 0529 * Note that while this enum is currently found in KNS3::Entry, 0530 * it will be moved to this class once the binary compatibility 0531 * lock is lifted for Frameworks 6. For now, you should read any 0532 * reference to the KNS3::Entry::Status enumerator as KNSCore::Entry::Status 0533 * 0534 * @param status New status of the entry 0535 */ 0536 void setStatus(KNS3::Entry::Status status); 0537 0538 /** 0539 * Retrieves the entry's status. 0540 * 0541 * @return Current status of the entry 0542 */ 0543 KNS3::Entry::Status status() const; 0544 0545 static KNSCore::EntryInternal fromEntry(const KNS3::Entry &entry); 0546 0547 private: 0548 QExplicitlySharedDataPointer<EntryInternalPrivate> d; 0549 }; 0550 0551 inline uint qHash(const KNSCore::EntryInternal &entry) 0552 { 0553 return qHash(entry.uniqueId()); 0554 } 0555 0556 } 0557 Q_DECLARE_METATYPE(KNSCore::EntryInternal::List) 0558 0559 #endif