KNewStuff

quickengine.h
1 /*
2  SPDX-FileCopyrightText: 2016 Dan Leinir Turthra Jensen <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 
7 #ifndef ENGINE_H
8 #define ENGINE_H
9 
10 #include <QObject>
11 #include <QQmlListProperty>
12 
13 #include "entrywrapper.h"
14 #include "errorcode.h"
15 #include "knewstuffquick_export.h"
16 
17 class EnginePrivate;
18 
19 /**
20  * @short Encapsulates a KNSCore::Engine for use in Qt Quick
21  *
22  * This class takes care of initialisation of a KNSCore::Engine when assigned a config file.
23  * The actual KNSCore:Engine can be read through the Engine::engine property.
24  *
25  * @see ItemsModel
26  */
27 class Engine : public QObject
28 {
29  Q_OBJECT
30 #if KNEWSTUFFQUICK_BUILD_DEPRECATED_SINCE(5, 81)
31  KNEWSTUFFQUICK_DEPRECATED_VERSION(5, 81, "Use NewStuff.Settings.allowedByKiosk instead")
32  Q_PROPERTY(bool allowedByKiosk READ allowedByKiosk CONSTANT)
33 #endif
34  Q_PROPERTY(QString configFile READ configFile WRITE setConfigFile NOTIFY configFileChanged)
35  Q_PROPERTY(QObject *engine READ engine NOTIFY engineChanged)
36  /**
37  * Whether or not the engine is performing its initial loading operations
38  * @since 5.65
39  */
41  Q_PROPERTY(bool hasAdoptionCommand READ hasAdoptionCommand NOTIFY engineInitialized)
42  Q_PROPERTY(QString name READ name NOTIFY engineInitialized)
43  Q_PROPERTY(QObject *categories READ categories NOTIFY categoriesChanged)
44  Q_PROPERTY(QStringList categoriesFilter READ categoriesFilter WRITE setCategoriesFilter RESET resetCategoriesFilter NOTIFY categoriesFilterChanged)
45  Q_PROPERTY(int filter READ filter WRITE setFilter NOTIFY filterChanged)
46  Q_PROPERTY(int sortOrder READ sortOrder WRITE setSortOrder NOTIFY sortOrderChanged)
47  Q_PROPERTY(QString searchTerm READ searchTerm WRITE setSearchTerm RESET resetSearchTerm NOTIFY searchTermChanged)
48  Q_PROPERTY(QObject *searchPresetModel READ searchPresetModel NOTIFY searchPresetModelChanged)
49 #if KNEWSTUFF_BUILD_DEPRECATED_SINCE(5, 82)
50  Q_PROPERTY(QQmlListProperty<KNSCore::EntryWrapper> changedEntries READ changedEntries NOTIFY changedEntriesChanged)
51  Q_PROPERTY(int changedEntriesCount READ changedEntriesCount NOTIFY changedEntriesChanged)
52 #endif
53  Q_PROPERTY(bool isValid READ isValid NOTIFY engineInitialized)
54 public:
55  explicit Engine(QObject *parent = nullptr);
56  ~Engine() override;
57 
58 #if KNEWSTUFFQUICK_BUILD_DEPRECATED_SINCE(5, 81)
59  KNEWSTUFFQUICK_DEPRECATED_VERSION(5, 81, "Use KNewStuffQuick::Settings::allowedByKiosk() instead")
60  bool allowedByKiosk() const;
61 #endif
62 
63  enum EntryEvent {
65  StatusChangedEvent = KNSCore::EntryInternal::StatusChangedEvent,
67  DetailsLoadedEvent = KNSCore::EntryInternal::DetailsLoadedEvent,
68  };
69  Q_ENUM(EntryEvent)
70 
71  /**
72  * Registering the error codes from KNSCore to allow them to be used easily in QtQuick
73  * @see KNSCore::ErrorCode
74  * @since 5.84
75  */
76  enum ErrorCode {
77  UnknownError = KNSCore::ErrorCode::UnknownError,
78  NetworkError = KNSCore::ErrorCode::NetworkError,
79  OcsError = KNSCore::ErrorCode::OcsError,
80  ConfigFileError = KNSCore::ErrorCode::ConfigFileError,
81  ProviderError = KNSCore::ErrorCode::ProviderError,
82  InstallationError = KNSCore::ErrorCode::InstallationError,
83  ImageError = KNSCore::ErrorCode::ImageError,
84  AdoptionError = KNSCore::ErrorCode::AdoptionError,
85  TryAgainLaterError = KNSCore::ErrorCode::TryAgainLaterError,
86  };
88 
89  QString configFile() const;
90  void setConfigFile(const QString &newFile);
91  Q_SIGNAL void configFileChanged();
92 
93  QObject *engine() const;
94  Q_SIGNAL void engineChanged();
95 
96  /**
97  * Whether or not the engine is performing its initial loading operations
98  * @since 5.65
99  */
100  bool isLoading() const;
101  /**
102  * Fired when the isLoading value changes
103  * @since 5.65
104  */
105  Q_SIGNAL void isLoadingChanged();
106 
107  bool hasAdoptionCommand() const;
108  QString name() const;
109  Q_SIGNAL void engineInitialized();
110 
111  QObject *categories() const;
112  Q_SIGNAL void categoriesChanged();
113 
114  QStringList categoriesFilter() const;
115  void setCategoriesFilter(const QStringList &newCategoriesFilter);
116  Q_INVOKABLE void resetCategoriesFilter();
117  Q_SIGNAL void categoriesFilterChanged();
118 
119  int filter() const;
120  void setFilter(int newFilter);
121  Q_SIGNAL void filterChanged();
122 
123  int sortOrder() const;
124  void setSortOrder(int newSortOrder);
125  Q_SIGNAL void sortOrderChanged();
126 
127  QString searchTerm() const;
128  void setSearchTerm(const QString &newSearchTerm);
129  Q_INVOKABLE void resetSearchTerm();
130  Q_SIGNAL void searchTermChanged();
131 
132  QObject *searchPresetModel() const;
133  Q_SIGNAL void searchPresetModelChanged();
134 
135 #if KNEWSTUFF_BUILD_DEPRECATED_SINCE(5, 82)
137  Q_INVOKABLE void resetChangedEntries();
138  Q_SIGNAL void changedEntriesChanged();
139  int changedEntriesCount() const;
140 #endif
141 
142  bool isValid();
143 Q_SIGNALS:
144  void message(const QString &message);
145  void idleMessage(const QString &message);
146  void busyMessage(const QString &message);
147  void errorMessage(const QString &message);
148 
149  /**
150  * This is fired for events related directly to a single EntryInternal instance
151  * The intermediate states Updating and Installing are not forwarded. In case you
152  * need those you have to listen to the signals of the KNSCore::Engine instance of the engine property.
153  *
154  * As an example, if you need to know when the status of an entry changes, you might write:
155  \code
156  function onEntryEvent(entry, event) {
157  if (event == NewStuff.Engine.StatusChangedEvent) {
158  myModel.ghnsEntryChanged(entry);
159  }
160  }
161  \endcode
162  *
163  * nb: The above example is also how one would port a handler for the old changedEntries signal
164  *
165  * @see EntryInternal::EntryEvent for details on which specific event is being notified
166  * @since 5.81
167  */
168  void entryEvent(KNSCore::EntryWrapper *entry, EntryEvent event);
169 
170  /**
171  * Fires in the case of any critical or serious errors, such as network or API problems.
172  * This forwards the signal from KNSCore::Engine::signalErrorCode, but with QML friendly
173  * enumerations.
174  * @param errorCode Represents the specific type of error which has occurred
175  * @param message A human-readable message which can be shown to the end user
176  * @param metadata Any additional data which might be hepful to further work out the details of the error (see KNSCore::EntryInternal::ErrorCode for the
177  * metadata details)
178  * @see KNSCore::Engine::signalErrorCode
179  * @since 5.84
180  */
181  void errorCode(const Engine::ErrorCode &errorCode, const QString &message, const QVariant &metadata);
182 
183 private:
184  const std::unique_ptr<EnginePrivate> d;
185 };
186 
187 #endif // ENGINE_H
Q_OBJECTQ_OBJECT
void errorCode(const Engine::ErrorCode &errorCode, const QString &message, const QVariant &metadata)
Fires in the case of any critical or serious errors, such as network or API problems.
Q_PROPERTY(...)
Encapsulates a KNSCore::Engine for use in Qt Quick.
Definition: quickengine.h:27
Q_ENUM(...)
@ DetailsLoadedEvent
Used when more details have been added to an existing entry (such as the full description),...
Definition: entryinternal.h:93
void entryEvent(KNSCore::EntryWrapper *entry, EntryEvent event)
This is fired for events related directly to a single EntryInternal instance The intermediate states ...
Q_SIGNAL void isLoadingChanged()
Fired when the isLoading value changes.
Q_SIGNALQ_SIGNAL
bool isLoading
Whether or not the engine is performing its initial loading operations.
Definition: quickengine.h:40
ErrorCode
Registering the error codes from KNSCore to allow them to be used easily in QtQuick.
Definition: quickengine.h:76
Wraps a KNSCore::EntryInternal in a QObject for passing through Qt Quick.
Definition: entrywrapper.h:38
@ StatusChangedEvent
Used when an event's status is set (use EntryInternal::status() to get the new status)
Definition: entryinternal.h:91
virtual bool event(QEvent *e)
@ UnknownEvent
A generic event, not generally used.
Definition: entryinternal.h:90
Q_INVOKABLEQ_INVOKABLE
Q_SIGNALSQ_SIGNALS
QObject * parent() const const
@ AdoptedEvent
Used when an entry has been successfully adopted (use this to determine whether a call to Engine::ado...
Definition: entryinternal.h:92
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Feb 7 2023 04:19:30 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.