KNewStuff

quickengine.h
1/*
2 SPDX-FileCopyrightText: 2016 Dan Leinir Turthra Jensen <admin@leinir.dk>
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 "categoriesmodel.h"
14#include "enginebase.h"
15#include "entry.h"
16#include "errorcode.h"
17#include "provider.h"
18#include "searchpresetmodel.h"
19#include "transaction.h"
20
21class EnginePrivate;
22
23/**
24 * KNSCore::EngineBase for interfacing with QML
25 *
26 * @see ItemsModel
27 */
29{
31 Q_PROPERTY(QString configFile READ configFile WRITE setConfigFile NOTIFY configFileChanged)
32 Q_PROPERTY(bool isLoading READ isLoading NOTIFY busyStateChanged)
33 Q_PROPERTY(bool needsLazyLoadSpinner READ needsLazyLoadSpinner NOTIFY busyStateChanged)
34 Q_PROPERTY(bool hasAdoptionCommand READ hasAdoptionCommand NOTIFY configFileChanged)
35 Q_PROPERTY(QString name READ name NOTIFY configFileChanged)
36 Q_PROPERTY(bool isValid READ isValid NOTIFY configFileChanged)
37
38 Q_PROPERTY(CategoriesModel *categories READ categories NOTIFY categoriesChanged)
39 Q_PROPERTY(QStringList categoriesFilter READ categoriesFilter WRITE setCategoriesFilter RESET resetCategoriesFilter NOTIFY categoriesFilterChanged)
40 Q_PROPERTY(KNSCore::Provider::Filter filter READ filter WRITE setFilter NOTIFY filterChanged)
41 Q_PROPERTY(KNSCore::Provider::SortMode sortOrder READ sortOrder WRITE setSortOrder NOTIFY sortOrderChanged)
42 Q_PROPERTY(QString searchTerm READ searchTerm WRITE setSearchTerm RESET resetSearchTerm NOTIFY searchTermChanged)
43 Q_PROPERTY(SearchPresetModel *searchPresetModel READ searchPresetModel NOTIFY searchPresetModelChanged)
44
45 /**
46 * Current state of the engine, the state con contain multiple operations
47 * an empty BusyState represents the idle status
48 * @since 5.74
49 */
51 Q_PROPERTY(QString busyMessage READ busyMessage NOTIFY busyStateChanged)
52public:
53 explicit Engine(QObject *parent = nullptr);
55
56 enum class BusyOperation {
57 Initializing = 1,
58 LoadingData,
59 LoadingPreview,
60 InstallingEntry,
61 };
62 Q_DECLARE_FLAGS(BusyState, BusyOperation)
63 Q_ENUM(BusyOperation)
64
65 enum EntryEvent { // TODO KF6 remove in favor of using NewStuff.Entry values
66 UnknownEvent = KNSCore::Entry::UnknownEvent,
67 StatusChangedEvent = KNSCore::Entry::StatusChangedEvent,
68 AdoptedEvent = KNSCore::Entry::AdoptedEvent,
69 DetailsLoadedEvent = KNSCore::Entry::DetailsLoadedEvent,
70 };
71 Q_ENUM(EntryEvent)
72
73 QString configFile() const;
74 void setConfigFile(const QString &newFile);
75 Q_SIGNAL void configFileChanged();
76
78 QString busyMessage() const;
79 void setBusyState(Engine::BusyState state);
80
81 /**
82 * Signal gets emitted when the busy state changes
83 * @since 5.74
84 */
86
87 /**
88 * Whether or not the engine is performing its initial loading operations
89 * @since 5.65
90 */
91 bool isLoading() const
92 {
93 // When installing entries, we don't want to block the UI
94 return busyState().toInt() != 0 && ((busyState() & BusyOperation::InstallingEntry) != BusyOperation::InstallingEntry);
95 }
96
97 CategoriesModel *categories() const;
98 Q_SIGNAL void categoriesChanged();
99
100 QStringList categoriesFilter() const;
101 void setCategoriesFilter(const QStringList &newCategoriesFilter);
102 Q_INVOKABLE void resetCategoriesFilter()
103 {
104 setCategoriesFilter(categoriesFilter());
105 }
106 Q_SIGNAL void categoriesFilterChanged();
107
108 KNSCore::Provider::Filter filter() const;
109 void setFilter(KNSCore::Provider::Filter filter);
110 Q_SIGNAL void filterChanged();
111
112 KNSCore::Provider::SortMode sortOrder() const;
113 void setSortOrder(KNSCore::Provider::SortMode newSortOrder);
114 Q_SIGNAL void sortOrderChanged();
115
116 QString searchTerm() const;
117 void setSearchTerm(const QString &newSearchTerm);
118 Q_INVOKABLE void resetSearchTerm()
119 {
120 setSearchTerm(QString());
121 }
122 Q_SIGNAL void searchTermChanged();
123
124 SearchPresetModel *searchPresetModel() const;
125 Q_SIGNAL void searchPresetModelChanged();
126
127 Q_INVOKABLE void updateEntryContents(const KNSCore::Entry &entry);
128 Q_INVOKABLE KNSCore::Entry __createEntry(const QString &providerId, const QString &entryId)
129 {
131 e.setProviderId(providerId);
133 return e;
134 }
135
136 bool isValid();
137 void reloadEntries();
138
139 void loadPreview(const KNSCore::Entry &entry, KNSCore::Entry::PreviewType type);
140
142
143 /**
144 * Adopt an entry using the adoption command. This will also take care of displaying error messages
145 * @param entry Entry that should be adopted
146 * @see signalErrorCode
147 * @see signalEntryEvent
148 * @since 5.77
149 */
150 Q_INVOKABLE void adoptEntry(const KNSCore::Entry &entry);
151
152 /**
153 * Installs an entry's payload file. This includes verification, if
154 * necessary, as well as decompression and other steps according to the
155 * application's *.knsrc file.
156 *
157 * @param entry Entry to be installed
158 *
159 * @see signalInstallationFinished
160 * @see signalInstallationFailed
161 */
162 Q_INVOKABLE void install(const KNSCore::Entry &entry, int linkId = 1);
163
164 /**
165 * Uninstalls an entry. It reverses the steps which were performed
166 * during the installation.
167 *
168 * @param entry The entry to deinstall
169 */
170 Q_INVOKABLE void uninstall(const KNSCore::Entry &entry);
171
172 void requestMoreData();
173
174 Q_INVOKABLE void revalidateCacheEntries();
175 Q_INVOKABLE void restoreSearch();
176 Q_INVOKABLE void storeSearch();
178 void signalResetView();
179
180 /**
181 * This is fired for events related directly to a single Entry instance
182 * The intermediate states Updating and Installing are not forwarded. In case you
183 * need those you have to listen to the signals of the KNSCore::Engine instance of the engine property.
184 *
185 * As an example, if you need to know when the status of an entry changes, you might write:
186 \code
187 function onEntryEvent(entry, event) {
188 if (event == NewStuff.Engine.StatusChangedEvent) {
189 myModel.ghnsEntryChanged(entry);
190 }
191 }
192 \endcode
193 *
194 * nb: The above example is also how one would port a handler for the old changedEntries signal
195 *
196 * @see Entry::EntryEvent for details on which specific event is being notified
197 */
199
200 /**
201 * Fires in the case of any critical or serious errors, such as network or API problems.
202 * This forwards the signal from KNSCore::Engine::signalErrorCode, but with QML friendly
203 * enumerations.
204 * @param errorCode Represents the specific type of error which has occurred
205 * @param message A human-readable message which can be shown to the end user
206 * @param metadata Any additional data which might be hepful to further work out the details of the error (see KNSCore::Entry::ErrorCode for the
207 * metadata details)
208 * @see KNSCore::Engine::signalErrorCode
209 * @since 5.84
210 */
211 void errorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata);
212
213 void entryPreviewLoaded(const KNSCore::Entry &, KNSCore::Entry::PreviewType);
214
215 void signalEntriesLoaded(const KNSCore::Entry::List &entries); ///@internal
217
218private:
219 bool init(const QString &configfile) override;
220 void updateStatus() override;
221 bool needsLazyLoadSpinner();
222 Q_SIGNAL void signalEntryPreviewLoaded(const KNSCore::Entry &, KNSCore::Entry::PreviewType);
223 void registerTransaction(KNSCore::Transaction *transactions);
224 void doRequest();
225 const std::unique_ptr<EnginePrivate> d;
226};
227
228#endif // ENGINE_H
A model which shows the categories found in an Engine.
KNSCore::EngineBase for interfacing with QML.
Definition quickengine.h:29
void signalEntryEvent(const KNSCore::Entry &entry, KNSCore::Entry::EntryEvent event)
void errorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata)
Fires in the case of any critical or serious errors, such as network or API problems.
bool isLoading() const
Whether or not the engine is performing its initial loading operations.
Definition quickengine.h:91
Q_INVOKABLE void install(const KNSCore::Entry &entry, int linkId=1)
Installs an entry's payload file.
Q_INVOKABLE void adoptEntry(const KNSCore::Entry &entry)
Adopt an entry using the adoption command.
Q_SIGNAL void busyStateChanged()
Signal gets emitted when the busy state changes.
BusyState busyState
Current state of the engine, the state con contain multiple operations an empty BusyState represents ...
Definition quickengine.h:50
void addProvider(QSharedPointer< KNSCore::Provider > provider) override
Add a provider and connect it to the right slots.
void entryEvent(const KNSCore::Entry &entry, KNSCore::Entry::EntryEvent event)
This is fired for events related directly to a single Entry instance The intermediate states Updating...
Q_INVOKABLE void uninstall(const KNSCore::Entry &entry)
Uninstalls an entry.
KNewStuff engine.
Definition enginebase.h:52
QSharedPointer< Provider > provider(const QString &providerId) const
The Provider instance with the passed ID.
KNewStuff data entry container.
Definition entry.h:48
@ StatusChangedEvent
Used when an event's status is set (use Entry::status() to get the new status)
Definition entry.h:122
@ UnknownEvent
A generic event, not generally used.
Definition entry.h:121
@ AdoptedEvent
Used when an entry has been successfully adopted (use this to determine whether a call to Engine::ado...
Definition entry.h:123
@ DetailsLoadedEvent
Used when more details have been added to an existing entry (such as the full description),...
Definition entry.h:124
void setUniqueId(const QString &id)
Set the object's unique ID.
Definition entry.cpp:125
KNewStuff Transaction.
Definition transaction.h:38
The SearchPresetModel class.
Int toInt() const const
Q_ENUM(...)
Q_INVOKABLEQ_INVOKABLE
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_SIGNALQ_SIGNAL
Q_SIGNALSQ_SIGNALS
virtual bool event(QEvent *e)
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:52:16 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.