KNewStuff

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

KDE's Doxygen guidelines are available online.