KNSCore::Engine

#include <engine.h>

Inheritance diagram for KNSCore::Engine:

Signals

void jobStarted (KJob *, const QString &)
 
void signalBusy (const QString &)
 
void signalCategoriesMetadataLoded (const QList< Provider::CategoryMetadata > &categories)
 
void signalDownloadDialogDone (KNSCore::EntryInternal::List)
 
void signalEntriesLoaded (const KNSCore::EntryInternal::List &entries)
 
void signalEntryChanged (const KNSCore::EntryInternal &entry)
 
void signalEntryDetailsLoaded (const KNSCore::EntryInternal &entry)
 
void signalEntryPreviewLoaded (const KNSCore::EntryInternal &, KNSCore::EntryInternal::PreviewType)
 
void signalEntryUploadFailed ()
 
void signalEntryUploadFinished ()
 
void signalError (const QString &)
 
void signalErrorCode (const KNSCore::ErrorCode &errorCode, const QString &message, const QVariant &metadata)
 
void signalIdle (const QString &)
 
void signalMessage (const QString &message)
 
void signalPreviewFailed ()
 
void signalProvidersLoaded ()
 
void signalResetView ()
 
void signalUpdateableEntriesLoaded (const KNSCore::EntryInternal::List &entries)
 

Public Member Functions

 Engine (QObject *parent=nullptr)
 
 ~Engine ()
 
void addDownloadTagFilter (const QString &filter)
 
void addTagFilter (const QString &filter)
 
QString adoptionCommand (const KNSCore::EntryInternal &entry) const
 
void becomeFan (const EntryInternal &entry)
 
QStringList categories () const
 
QStringList categoriesFilter () const
 
QList< Provider::CategoryMetadatacategoriesMetadata ()
 
void checkForInstalled ()
 
void checkForUpdates ()
 
CommentsModelcommentsForEntry (const KNSCore::EntryInternal &entry)
 
void contactAuthor (const EntryInternal &entry)
 
QSharedPointer< ProviderdefaultProvider () const
 
QStringList downloadTagFilter () const
 
void fetchEntryById (const QString &id)
 
Provider::Filter filter () const
 
bool hasAdoptionCommand () const
 
bool init (const QString &configfile)
 
void install (KNSCore::EntryInternal entry, int linkId=1)
 
void loadDetails (const KNSCore::EntryInternal &entry)
 
void loadPreview (const KNSCore::EntryInternal &entry, EntryInternal::PreviewType type)
 
QString name () const
 
QSharedPointer< Providerprovider (const QString &providerId) const
 
void reloadEntries ()
 
void requestData (int page, int pageSize)
 
void requestMoreData ()
 
QString searchTerm () const
 
void setCategoriesFilter (const QStringList &categories)
 
void setConfigLocationFallback (bool enableFallback)
 
void setDownloadTagFilter (const QStringList &filter)
 
void setFilter (Provider::Filter filter)
 
void setPageSize (int pageSize)
 
void setSearchTerm (const QString &searchString)
 
void setSortMode (Provider::SortMode mode)
 
void setTagFilter (const QStringList &filter)
 
Provider::SortMode sortMode () const
 
QStringList tagFilter () const
 
void uninstall (KNSCore::EntryInternal entry)
 
bool userCanBecomeFan (const EntryInternal &entry)
 
bool userCanVote (const EntryInternal &entry)
 
void vote (const EntryInternal &entry, uint rating)
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Static Public Member Functions

static QStringList configSearchLocations (bool includeFallbackLocations=false)
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Detailed Description

KNewStuff engine.

An engine keeps track of data which is available locally and remote and offers high-level synchronization calls as well as upload and download primitives using an underlying GHNS protocol.

Definition at line 70 of file engine.h.

Constructor & Destructor Documentation

Engine::Engine ( QObject parent = nullptr)
explicit

Constructor.

Definition at line 79 of file engine.cpp.

Engine::~Engine ( )

Destructor.

Frees up all the memory again which might be taken by cached entries and providers.

Definition at line 102 of file engine.cpp.

Member Function Documentation

void Engine::addDownloadTagFilter ( const QString filter)

Add a single filter entry to the download tag filter.

The filter should be in the same form as the filter lines in the list used by setDownloadsTagFilter(QStringList)

Parameters
filterThe filter in the form of a string
See also
setTagFilter(QStringList)
setDownloadTagFilter(QStringList)
Since
5.51

Definition at line 512 of file engine.cpp.

void Engine::addTagFilter ( const QString filter)

Add a single filter entry to the entry tag filter.

The filter should be in the same form as the filter lines in the list used by setTagFilter(QStringList)

Parameters
filterThe filter in the form of a string
See also
setTagFilter(QStringList)
Since
5.51

Definition at line 491 of file engine.cpp.

QString Engine::adoptionCommand ( const KNSCore::EntryInternal entry) const

The adoption command can be used to allow a user to make use of an entry's installed data.

For example, this command might be used to ask the system to switch to a wallpaper or icon theme which was installed with KNS.

The following is how this might look in a knsrc file. The example shows how an external tool is called on the directory containing the installed file represented by d. If you wish to directly point to the installed file, the substitution variable is f.

AdoptionCommand=/usr/lib64/libexec/plasma-changeicons d
Parameters
entryThe entry to return an adoption command for
Returns
The command to run to adopt this entry's installed data

Definition at line 873 of file engine.cpp.

void Engine::becomeFan ( const EntryInternal entry)

This will mark the user who is currently authenticated as a fan of the entry passed to the function.

Parameters
entryThe entry the user wants to be a fan of

Definition at line 796 of file engine.cpp.

QStringList Engine::categories ( ) const

The list of the server-side names of the categories handled by this engine instance.

This corresponds directly to the list of categories in your knsrc file. This is not supposed to be used as user-facing strings -

See also
categoriesMetadata() for that.
Returns
The categories which this instance of Engine handles

Definition at line 210 of file engine.cpp.

QStringList Engine::categoriesFilter ( ) const

The list of categories searches will actually show results from.

This is a subset of the categories() list.

See also
KNSCore::Engine::setCategoriesFilter(QString)

Definition at line 215 of file engine.cpp.

QList< Provider::CategoryMetadata > Engine::categoriesMetadata ( )

The list of metadata for the categories handled by this engine instance.

If you wish to show the categories to the user, this is the data to use. The category name is the string used to set categories for the filter, and also what is returned by both categories() and categoriesFilter(). The human-readable name is displayName, and the only thing which should be shown to the user.

Returns
The metadata for all categories handled by this engine

Definition at line 220 of file engine.cpp.

void Engine::checkForInstalled ( )

Requests installed packages with an up to date state.

See also
signalEntriesLoaded()

Definition at line 823 of file engine.cpp.

void Engine::checkForUpdates ( )

Request for packages that are installed and need update.

These will be reported through the signal

See also
signalUpdateableEntriesLoaded().

Definition at line 815 of file engine.cpp.

KNSCore::CommentsModel * Engine::commentsForEntry ( const KNSCore::EntryInternal entry)

This function will return an instance of a model which contains comments for the entry passed to it.

The model may be empty (if there are no comments for the entry, which also covers situations where the entry's provider does not support commenting)

Parameters
entryThe entry to fetch comments for
Returns
A model which contains the comments for the specified entry
Since
5.63

Definition at line 938 of file engine.cpp.

QStringList Engine::configSearchLocations ( bool  includeFallbackLocations = false)
static

Get a list of all the locations which will be used when searching for knsrc files, in the order in which the search will occur.

Parameters
includeFallbackLocationsWhether or not the deprecated search locations are included
Returns
The search list for knsrc files
Since
5.57

Definition at line 908 of file engine.cpp.

void Engine::contactAuthor ( const EntryInternal entry)

Try to contact the author of the entry by email or showing their homepage.

Definition at line 757 of file engine.cpp.

QSharedPointer< KNSCore::Provider > Engine::defaultProvider ( ) const

Return the first provider in the providers list (usually the default provider)

Returns
The first Provider (or null if the engine is not initialized)
Since
5.63

Definition at line 931 of file engine.cpp.

QStringList Engine::downloadTagFilter ( ) const

Gets the current downloadlink tag filter list.

See also
setDownloadTagFilter(QStringList)
Since
5.51

Definition at line 507 of file engine.cpp.

void Engine::fetchEntryById ( const QString id)

Convenience method to launch a search for one specific entry.

Note
it will reset the engine state
Parameters
idThe ID of the entry you wish to fetch

Definition at line 447 of file engine.cpp.

Provider::Filter Engine::filter ( ) const

The result filter set on the current request.

See also
setFilter(Provider::Filter)
Since
5.63

Definition at line 442 of file engine.cpp.

bool Engine::hasAdoptionCommand ( ) const

Whether or not an adoption command exists for this engine.

See also
adoptionCommand(KNSCore::EntryInternal)
Returns
True if an adoption command exists

Definition at line 898 of file engine.cpp.

bool Engine::init ( const QString configfile)

Initializes the engine.

This step is application-specific and relies on an external configuration file, which determines all the details about the initialization.

Parameters
configfileKNewStuff2 configuration file (*.knsrc)
Returns
true if any valid configuration was found, false otherwise
See also
KNS3::DownloadDialog

TODO KF6: This is fallback logic for an old location for the knsrc files. This should be considered deprecated in KF5, and it would make a lot of sense to disable it entirely for KF6

Definition at line 113 of file engine.cpp.

void Engine::install ( KNSCore::EntryInternal  entry,
int  linkId = 1 
)

Installs an entry's payload file.

This includes verification, if necessary, as well as decompression and other steps according to the application's *.knsrc file.

Parameters
entryEntry to be installed
See also
signalInstallationFinished
signalInstallationFailed

Definition at line 555 of file engine.cpp.

void Engine::loadDetails ( const KNSCore::EntryInternal entry)

Get the full details of a specific entry.

Parameters
entryThe entry to get full details for
See also
Entry::signalEntryDetailsLoaded(KNSCore::EntryInternal)

Definition at line 725 of file engine.cpp.

void Engine::loadPreview ( const KNSCore::EntryInternal entry,
EntryInternal::PreviewType  type 
)

Attempt to load a specific preview for the specified entry.

Parameters
entryThe entry to fetch a preview for
typeThe particular preview to fetch
See also
signalEntryPreviewLoaded(KNSCore::EntryInternal, KNSCore::EntryInternal::PreviewType);
signalPreviewFailed();

Definition at line 731 of file engine.cpp.

QString Engine::name ( ) const

The name as defined by the knsrc file.

Returns
The name associated with the engine's configuration file
Since
5.63

Definition at line 205 of file engine.cpp.

QSharedPointer< KNSCore::Provider > Engine::provider ( const QString providerId) const

The Provider instance with the passed ID.

Parameters
providerIdThe ID of the Provider to fetch
Returns
The Provider with the passed ID, or null if non such Provider exists
Since
5.63

Definition at line 926 of file engine.cpp.

QString Engine::searchTerm ( ) const

The search term for the current search (empty if none is set)

Returns
The current search term
Since
5.63

Definition at line 473 of file engine.cpp.

void Engine::setCategoriesFilter ( const QStringList categories)

Set the categories that will be included in searches.

Note: This will automatically launch a search, which means you do not need to call requestData manually.

See also
KNSCore::Engine::categories()
Parameters
categoriesA list of strings of categories

Definition at line 413 of file engine.cpp.

void Engine::setConfigLocationFallback ( bool  enableFallback)

Sets whether or not the config file location discovery fallback should be active.

If enabled (default), if the config file is not found in the knsrcfiles location, then the engine will also look in the systemwide config location (usually /etc/xdg on linux). If disabled, this fallback location will not be searched.

Parameters
enableFallbackWhether or not the fallback discovery should be enabled
Since
5.57

Definition at line 921 of file engine.cpp.

void Engine::setDownloadTagFilter ( const QStringList filter)

Sets a filter to be applied to the downloads for an entry.

The logic is the same as used in setTagFilter(QStringList), but vitally, only one downloadlink is required to match the filter for the list to be valid. If you do not wish to show the others in your client, you must hide them yourself.

For an entry to be accepted when a download tag filter is set, it must also be accepted by the entry filter (so, for example, while a list of downloads might be accepted, if the entry has ghns_excluded set, and the default entry filter is set, the entry will still be filtered out).

In your knsrc file, set DownloadTagFilter to the filter you wish to apply, using the same logic as described for the entry tagfilter.

Parameters
filterThe filter in the form of a list of strings
See also
setTagFilter(QStringList)
Since
5.51

Definition at line 499 of file engine.cpp.

void Engine::setFilter ( Provider::Filter  filter)

Set a filter for results (defaults to none), which will allow you to show only installed entries, installed entries which have updates, or a specific item with a specified ID.

The latter further requires the search term to be the exact ID of the entry you wish to retrieve.

Note: This will automatically launch a search, which means you do not need to call requestData manually.

See also
fetchEntryById(QString)
setSearchTerm(QString)
Parameters
filterThe type of results you wish to see

Definition at line 433 of file engine.cpp.

void Engine::setPageSize ( int  pageSize)

Set the page size for requests not made explicitly with requestData(int,int)

Parameters
pageSizethe default number of entries to request from the provider
See also
requestData(int,int)

Definition at line 903 of file engine.cpp.

void Engine::setSearchTerm ( const QString searchString)

Sets a string search term.

Note: This will automatically launch a search, which means you do not need to call requestData manually.

Parameters
searchStringThe search term you wish to search for

Definition at line 461 of file engine.cpp.

void Engine::setSortMode ( Provider::SortMode  mode)

Set the order the search results are returned in.

Search requests default to showing the newest entries first.

Note: This will automatically launch a search, which means you do not need to call requestData manually.

See also
KNSCore::Provider::SearchRequest
Parameters
modeThe order you want search results to come back in.

Definition at line 419 of file engine.cpp.

void Engine::setTagFilter ( const QStringList filter)

Set a filter for results, which filters out all entries which do not match the filter, as applied to the tags for the entry.

This filters only on the tags specified for the entry itself. To filter the downloadlinks, use setDownloadTagFilter(QStringList).

Note
The default filter if one is not set from your knsrc file will filter out entries marked as ghns_excluded=1. To retain this when setting a custom filter, add "ghns_excluded!=1" as one of the filters.
Some tags provided by OCS do not supply a value (and are simply passed as a key). These will be interpreted as having the value 1 for filtering purposes. An example of this might be ghns_excluded, which in reality will generally be passed through ocs as "ghns_excluded" rather than "ghns_excluded=1"
As tags are metadata, they are provided in the form of adjectives. They are never supplied as action verbs or instructions (as an example, a good tag to suggest that for example a wallpaper is painted would be "painted" as opposed to "paint", and another example might be that an item should be "excluded" as opposed to "exclude").

== Examples of use == Value for tag "tagname" must be exactly "tagdata": tagname==tagdata

Value for tag "tagname" must be different from "tagdata": tagname!=tagdata

== KNSRC entry == A tag filter line in a .knsrc file, which is a comma separated list of tag/value pairs, might look like:

TagFilter=ghns_excluded!=1,data##mimetype==application/cbr+zip,data##mimetype==application/cbr+rar which would honour the exclusion and filter out anything that does not include a comic book archive in either zip or rar format in one or more of the download items. Notice in particular that there are two data##mimetype entries. Use this for when a tag may have multiple values.

TagFilter=application##architecture==x86_64 which would not honour the exclusion, and would filter out all entries which do not mark themselves as having a 64bit application binary in at least one download item.

The value does not current suppport wildcards. The list should be considered a binary AND operation (that is, all filter entries must match for the data entry to be included in the return data)

Parameters
filterThe filter in the form of a list of strings
See also
setDownloadTagFilter(QStringList)
Since
5.51

Definition at line 478 of file engine.cpp.

void KNSCore::Engine::signalErrorCode ( const KNSCore::ErrorCode errorCode,
const QString message,
const QVariant metadata 
)
signal

Fires in the case of any critical or serious errors, such as network or API problems.

Parameters
errorCodeRepresents the specific type of error which has occurred
messageA human-readable message which can be shown to the end user
metadataAny additional data which might be hepful to further work out the details of the error (see KNSCore::EntryInternal::ErrorCode for the metadata details)
See also
KNSCore::EntryInternal::ErrorCode
Since
5.53
void KNSCore::Engine::signalMessage ( const QString message)
signal

Indicates a message to be added to the ui's log, or sent to a messagebox.

Provider::SortMode Engine::sortMode ( ) const

The sort mode set on the current request.

See also
setSortMode(Provider::SortMode)
Since
5.63

Definition at line 428 of file engine.cpp.

QStringList Engine::tagFilter ( ) const

Gets the current tag filter list.

See also
setTagFilter(QStringList)
Since
5.51

Definition at line 486 of file engine.cpp.

void Engine::uninstall ( KNSCore::EntryInternal  entry)

Uninstalls an entry.

It reverses the steps which were performed during the installation.

Parameters
entryThe entry to deinstall

Definition at line 696 of file engine.cpp.

bool Engine::userCanBecomeFan ( const EntryInternal entry)

Whether or not the user is allowed to become a fan of a particular entry.

Not all providers (and consequently entries) support the fan functionality and you can use this function to determine this ability.

Parameters
entryThe entry the user might wish to be a fan of
Returns
Whether or not it is possible for the user to become a fan of that entry

Definition at line 790 of file engine.cpp.

bool Engine::userCanVote ( const EntryInternal entry)

Whether or not a user is able to vote on the passed entry.

Parameters
entryThe entry to check votability on
Returns
True if the user is able to vote on the entry

Definition at line 778 of file engine.cpp.

void Engine::vote ( const EntryInternal entry,
uint  rating 
)

Cast a vote on the passed entry.

Parameters
entryThe entry to vote on
ratingA number from 0 to 100, 50 being neutral, 0 being most negative and 100 being most positive.

Definition at line 784 of file engine.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Aug 6 2020 22:41:09 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.