Search for usage in LXR

#include <KPluginMetaData>

Inheritance diagram for KPluginMetaData:


QVariantList authors
QString category
QString copyrightText
QStringList dependencies
QString description
QString extraInformation
QString fileName
QStringList formFactors
QString iconName
int initialPreference
bool isEnabledByDefault
bool isHidden
bool isValid
QString license
QString licenseText
QString metaDataFileName
QStringList mimeTypes
QString name
QVariantList otherContributors
QString pluginId
QJsonObject rawData
QStringList serviceTypes
QVariantList translators
QString version
QString website

Public Member Functions

 KPluginMetaData ()
 KPluginMetaData (const KPluginLoader &loader)
 KPluginMetaData (const QPluginLoader &loader)
 KPluginMetaData (const QString &file)
 KPluginMetaData (const QJsonObject &metaData, const QString &file)
 KPluginMetaData (const QJsonObject &metaData, const QString &pluginFile, const QString &metaDataFile)
 KPluginMetaData (const KPluginMetaData &)
 ~KPluginMetaData ()
QList< KAboutPersonauthors () const
QString category () const
QString copyrightText () const
QStringList dependencies () const
QString description () const
QString extraInformation () const
QString fileName () const
QStringList formFactors () const
QString iconName () const
int initialPreference () const
QObjectinstantiate () const
bool isEnabledByDefault () const
bool isHidden () const
bool isValid () const
QString license () const
QString licenseText () const
QString metaDataFileName () const
QStringList mimeTypes () const
QString name () const
bool operator!= (const KPluginMetaData &other) const
KPluginMetaDataoperator= (const KPluginMetaData &)
bool operator== (const KPluginMetaData &other) const
QList< KAboutPersonotherContributors () const
QString pluginId () const
QJsonObject rawData () const
QStringList serviceTypes () const
bool supportsMimeType (const QString &mimeType) const
QList< KAboutPersontranslators () const
QString value (const QString &key, const QString &defaultValue=QString()) const
QString version () const
QString website () const

Static Public Member Functions

static KPluginMetaData findPluginById (const QString &directory, const QString &pluginId)
static KPluginMetaData fromDesktopFile (const QString &file, const QStringList &serviceTypes=QStringList())
static QStringList readStringList (const QJsonObject &jo, const QString &key)
static QString readTranslatedString (const QJsonObject &jo, const QString &key, const QString &defaultValue=QString())
static QJsonValue readTranslatedValue (const QJsonObject &jo, const QString &key, const QJsonValue &defaultValue=QJsonValue())

Detailed Description

This class allows easily accessing some standardized values from the JSON metadata that can be embedded into Qt plugins.

Additional plugin-specific metadata can be retrieved by directly reading from the QJsonObject returned by KPluginMetaData::rawData().

This class can be used instead of KPluginInfo from KService for applications that only load Qt C++ plugins.

The following keys will be read from an object "KPlugin" inside the metadata JSON:

Key Accessor function JSON Type
Name name() string
Description description() string
ExtraInformation extraInformation() string
Icon iconName() string
Authors authors() object array (KAboutPerson)
Category category() string
License license() string
Copyright copyrightText() string
Id pluginId() string
Version version() string
Website website() string
EnabledByDefault isEnabledByDefault() bool
ServiceTypes serviceTypes() string array
MimeTypes mimeTypes() string array
FormFactors formFactors() string array
Translators translators() object array (KAboutPerson)
OtherContributors otherContributors() object array (KAboutPerson)

The Authors, Translators and OtherContributors keys are expected to be list of objects that match the structure expected by KAboutPerson::fromJSON().

An example metadata json file could look like this:

  "KPlugin": {
     "Name": "Date and Time",
     "Description": "Date and time by timezone",
     "Icon": "preferences-system-time",
     "Authors": { "Name": "Aaron Seigo", "Email": "[email protected]" },
     "Category": "Date and Time",
     "EnabledByDefault": "true",
     "License": "LGPL",
     "Id": "time",
     "Version": "1.0",
     "Website": ""
See also

Definition at line 84 of file kpluginmetadata.h.

Constructor & Destructor Documentation

KPluginMetaData::KPluginMetaData ( )

Creates an invalid KPluginMetaData instance.

Definition at line 29 of file kpluginmetadata.cpp.

KPluginMetaData::KPluginMetaData ( const KPluginLoader loader)

Reads the plugin metadata from a KPluginLoader instance.

You must call KPluginLoader::setFileName() or use the appropriate constructor on loader before calling this.

Definition at line 93 of file kpluginmetadata.cpp.

KPluginMetaData::KPluginMetaData ( const QPluginLoader loader)

Reads the plugin metadata from a QPluginLoader instance.

You must call QPluginLoader::setFileName() or use the appropriate constructor on loader before calling this.

Definition at line 87 of file kpluginmetadata.cpp.

KPluginMetaData::KPluginMetaData ( const QString file)

Reads the plugin metadata from a plugin or .desktop which can be loaded from file.

For plugins, platform-specific library suffixes may be omitted since file will be resolved using the same logic as QPluginLoader.

If the file name ends with ".desktop", the .desktop file will be parsed instead of reading the metadata from the QPluginLoader. This is the same as calling KPluginMetaData::fromDesktopFile() without the serviceTypes parameter.

If file ends with .json, the file will be loaded as the QJsonObject metadata.

See also

Definition at line 52 of file kpluginmetadata.cpp.

KPluginMetaData::KPluginMetaData ( const QJsonObject metaData,
const QString file 

Creates a KPluginMetaData from a QJsonObject holding the metadata and a file name This can be used if the data is not retrieved from a Qt C++ plugin library but from some other source.

See also
KPluginMetaData(const QJsonObject &, const QString &, const QString &)

Definition at line 99 of file kpluginmetadata.cpp.

KPluginMetaData::KPluginMetaData ( const QJsonObject metaData,
const QString pluginFile,
const QString metaDataFile 

Creates a KPluginMetaData.

metaDatathe JSON metadata to use for this object
pluginFilethe file that the plugin can be loaded from
metaDataFilethe file that the JSON metadata was read from

This can be used if the data is not retrieved from a Qt C++ plugin library but from some other source.


Definition at line 105 of file kpluginmetadata.cpp.

KPluginMetaData::KPluginMetaData ( const KPluginMetaData other)

Copy contructor.

Definition at line 33 of file kpluginmetadata.cpp.

KPluginMetaData::~KPluginMetaData ( )


Definition at line 48 of file kpluginmetadata.cpp.

Member Function Documentation

QList<KAboutPerson> KPluginMetaData::authors ( ) const
the author(s) of this plugin.
QString KPluginMetaData::category ( ) const
the categories of this plugin (e.g. "playlist/skin").
QString KPluginMetaData::copyrightText ( ) const
a short copyright statement
QStringList KPluginMetaData::dependencies ( ) const
a list of plugins that this plugin depends on so that it can function properly
See also
Since 5.79, plugin dependencies are deprecated and will be removed in KF6
QString KPluginMetaData::description ( ) const
a short description of the plugin.
QString KPluginMetaData::extraInformation ( ) const
additional information about this plugin (e.g. for use in an "about plugin" dialog)
QString KPluginMetaData::fileName ( ) const
the path to the plugin. This string can be passed to the KPluginLoader or QPluginLoader constructors in order to attempt to load this plugin.
It is not guaranteed that this is a valid path to a shared library (i.e. loadable by QPluginLoader) since the metadata could also refer to a non-C++ plugin.
KPluginMetaData KPluginMetaData::findPluginById ( const QString directory,
const QString pluginId 
directoryThe directory to search for plugins. If a relative path is given for directory, all entries of QCoreApplication::libraryPaths() will be checked with directory appended as a subdirectory. If an absolute path is given only that directory will be searched.
Check if the returned KPluginMetaData is valid before continuing to use it.
pluginIdThe Id of the plugin. The id should be the same as the filename, see KPluginMetaData::pluginId().

Definition at line 115 of file kpluginmetadata.cpp.

QStringList KPluginMetaData::formFactors ( ) const
A string list of formfactors this plugin is useful for, e.g. desktop, tablet, handset, mediacenter, etc. The keys for this are not formally defined.
KPluginMetaData KPluginMetaData::fromDesktopFile ( const QString file,
const QStringList serviceTypes = QStringList() 

Load a KPluginMetaData instace from a .desktop file.

Unlike the constructor which takes a single file parameter this method allows you to specify which service type files should be parsed to determine the correct type for a given .desktop property. This ensures that a e.g. comma-separated string list field in the .desktop file will correctly be converted to a JSON string array.

This function mostly exists for backwards-compatibility. It is recommended that new applications load JSON files directly instead of using .desktop files for plugin metadata.
filethe .desktop file to load
serviceTypesa list of files to parse If one of these paths is a relative path it will be resolved relative to the "kservicetypes5" subdirectory in QStandardPaths::GenericDataLocation. If the list is empty only the default set of properties will be treated specially and all other entries will be read as the JSON string type.

Definition at line 149 of file kpluginmetadata.cpp.

QString KPluginMetaData::iconName ( ) const
the icon name for this plugin
See also
int KPluginMetaData::initialPreference ( ) const
the initial preference of the plugin. This is the preference to associate with this plugin initially (before the user has had any chance to define preferences for it). Higher values indicate stronger preference.
QObject * KPluginMetaData::instantiate ( ) const

Tries to instantiate this plugin using KPluginMetaData::fileName().

The value of KPluginMetaData::dependencies() is not used here, dependencies must be resolved manually.
The plugin root object or nullptr if it could not be loaded
See also
QPluginLoader::instance(), KPluginLoader::instance()

Definition at line 449 of file kpluginmetadata.cpp.

bool KPluginMetaData::isEnabledByDefault ( ) const
whether the plugin should be enabled by default. This is only a recommendation, applications can ignore this value if they want to.
bool KPluginMetaData::isHidden ( ) const
whether this object should be hidden, this is usually not used for binary plugins, when loading a KPluginMetaData from a .desktop file, this will reflect the value of the "Hidden" key.
bool KPluginMetaData::isValid ( ) const
whether this object holds valid information about a plugin. If this is true pluginId() will return a non-empty string.
QString KPluginMetaData::license ( ) const
the short license identifier (e.g. LGPL).
See also
KAboutLicense::byKeyword() for retrieving the full license information
QString KPluginMetaData::licenseText ( ) const
the text of the license, equivalent to KAboutLicense::byKeyword(license()).text()
QString KPluginMetaData::metaDataFileName ( ) const
the file that the metadata was read from. This is not necessarily the same as fileName(), since not all plugins have the metadata embedded. The metadata could also be stored in a separate .desktop file.
QStringList KPluginMetaData::mimeTypes ( ) const
a list of MIME types this plugin can handle (e.g. "application/pdf", "image/png", etc.)
QString KPluginMetaData::name ( ) const
the user visible name of the plugin.
bool KPluginMetaData::operator!= ( const KPluginMetaData other) const
true if this object is not equal to other, otherwise false.

Definition at line 444 of file kpluginmetadata.h.

KPluginMetaData & KPluginMetaData::operator= ( const KPluginMetaData other)

Copy assignment.

Definition at line 40 of file kpluginmetadata.cpp.

bool KPluginMetaData::operator== ( const KPluginMetaData other) const
true if this object is equal to other, otherwise false

Definition at line 444 of file kpluginmetadata.cpp.

QList<KAboutPerson> KPluginMetaData::otherContributors ( ) const
a list of people that contributed to this plugin (other than the authors and translators).
QString KPluginMetaData::pluginId ( ) const
the internal name of the plugin If the Id property is not set in the metadata, this will return the plugin file name without the file extension.
QJsonObject KPluginMetaData::rawData ( ) const
the full metadata stored inside the plugin file.
QStringList KPluginMetaData::readStringList ( const QJsonObject jo,
const QString key 
the value for key inside jo as a string list. If the type of key is string, a list with containing just that string will be returned, if it is an array the list will contain one entry for each array member. If the key cannot be found an empty list will be returned.

Definition at line 205 of file kpluginmetadata.cpp.

QString KPluginMetaData::readTranslatedString ( const QJsonObject jo,
const QString key,
const QString defaultValue = QString() 
the translated value of key from jo as a string or defaultValue if key was not found or the value for key is not of type string
See also
KPluginMetaData::readTranslatedValue(const QJsonObject &jo, const QString &key)

Definition at line 246 of file kpluginmetadata.cpp.

QJsonValue KPluginMetaData::readTranslatedValue ( const QJsonObject jo,
const QString key,
const QJsonValue defaultValue = QJsonValue() 

Reads a value from jo but unlike QJsonObject::value() it allows different entries for each locale This is done by appending the locale identifier in brackets to the key (e.g.

"[de_DE]" or "[es]") When looking for a key "foo" with German (Germany) locale we will first attempt to read "foo[de_DE]", if that does not exist "foo[de]", finally falling back to "foo" if that also doesn't exist.

the translated value for key from jo or defaultValue if key was not found

Definition at line 226 of file kpluginmetadata.cpp.

QStringList KPluginMetaData::serviceTypes ( ) const

Returns the service types that this plugin implements.

This is mostly for historical / compatibility purposes. As a general rule, instead of opening many plugins to then filter by servicetype, put all plugins of the same type in a subdirectory, that you can pass to findPlugins directly. No point in opening 20 plugins to pick out only 3, when the filesystem can do that filtering for you.

Unlike KService this does not contain the MIME types. To get the handled MIME types use the KPluginMetaData::mimeTypes() function.
a list of service types this plugin implements (e.g. "Plasma/DataEngine")
bool KPluginMetaData::supportsMimeType ( const QString mimeType) const
true if this plugin can handle the given mimetype This is more accurate than mimeTypes().contains(mimeType) because it also takes MIME type inheritance into account.

Definition at line 377 of file kpluginmetadata.cpp.

QList<KAboutPerson> KPluginMetaData::translators ( ) const
the translator(s) of this plugin.
QString KPluginMetaData::value ( const QString key,
const QString defaultValue = QString() 
) const
the value for key from the metadata or defaultValue if the key does not exist or the value for key is not of type string
See also
KPluginMetaData::rawData() if QString is not the correct type for key

Definition at line 421 of file kpluginmetadata.cpp.

QString KPluginMetaData::version ( ) const
the version of the plugin.
QString KPluginMetaData::website ( ) const
the website of the plugin.

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Jul 26 2021 23:02:21 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.