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 "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 ([email protected])
46  * \par Maintainer:
47  * Jeremy Whiting ([email protected])
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 
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
KNEWSTUFFCORE_EXPORT QString replaceBBCode(const QString &unformattedText)
function to remove bb code formatting that opendesktop sends
Contains the core functionality for handling interaction with NewStuff providers. ...
Source
Source of the entry, A entry&#39;s data is coming from either cache, or an online provider this helps the...
Definition: entryinternal.h:59
KNewStuff author information.
Definition: core/author.h:30
EntryType
Represents whether the current entry is an actual catalog entry, or an entry that represents a set of...
Definition: entryinternal.h:97
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
KNewStuff data entry container.
Definition: entryinternal.h:49
The namespace for the KNewStuff classes.
Definition: button.cpp:19
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Oct 26 2021 22:43:05 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.