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