KPluginMetaData
#include <KPluginMetaData>

Public Types | |
enum | KPluginMetaDataOption { DoNotAllowEmptyMetaData, AllowEmptyMetaData } |
Properties | |
QList< KAboutPerson > | authors |
QString | bugReportUrl |
QString | category |
QString | copyrightText |
QString | description |
QString | fileName |
QStringList | formFactors |
QString | iconName |
bool | isEnabledByDefault |
bool | isHidden |
bool | isValid |
QString | license |
QString | licenseText |
QStringList | mimeTypes |
QString | name |
QList< KAboutPerson > | otherContributors |
QString | pluginId |
QJsonObject | rawData |
QList< KAboutPerson > | translators |
QString | version |
QString | website |
Public Member Functions | |
KPluginMetaData () | |
KPluginMetaData (const KPluginMetaData &) | |
KPluginMetaData (const QJsonObject &metaData, const QString &fileName) | |
KPluginMetaData (const QPluginLoader &loader) | |
KPluginMetaData (const QString &pluginFile, KPluginMetaDataOption option=KPluginMetaDataOption::DoNotAllowEmptyMetaData) | |
~KPluginMetaData () | |
QList< KAboutPerson > | authors () const |
QString | bugReportUrl () const |
QString | category () const |
QString | copyrightText () const |
QString | description () const |
QString | fileName () const |
QStringList | formFactors () const |
QString | iconName () const |
template<typename T > | |
bool | isEnabled (const T &config) const |
bool | isEnabledByDefault () const |
bool | isHidden () const |
bool | isStaticPlugin () const |
bool | isValid () const |
QString | license () const |
QString | licenseText () const |
QStringList | mimeTypes () const |
QString | name () const |
bool | operator!= (const KPluginMetaData &other) const |
KPluginMetaData & | operator= (const KPluginMetaData &) |
bool | operator== (const KPluginMetaData &other) const |
QList< KAboutPerson > | otherContributors () const |
QString | pluginId () const |
QJsonObject | rawData () const |
bool | supportsMimeType (const QString &mimeType) const |
QList< KAboutPerson > | translators () const |
bool | value (const QString &key, bool defaultValue) const |
QString | value (const QString &key, const char *ch) const =delete |
QString | value (const QString &key, const QString &defaultValue=QString()) const |
QStringList | value (const QString &key, const QStringList &defaultValue) const |
int | value (const QString &key, int defaultValue) const |
QString | version () const |
QString | website () const |
Static Public Member Functions | |
static KPluginMetaData | findPluginById (const QString &directory, const QString &pluginId) |
static QList< KPluginMetaData > | findPlugins (const QString &directory, std::function< bool(const KPluginMetaData &)> filter, KPluginMetaDataOption option) |
static QList< KPluginMetaData > | findPlugins (const QString &directory, std::function< bool(const KPluginMetaData &)> filter={}) |
static KPluginMetaData | fromJsonFile (const QString &jsonFile) |
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().
For embedded metadata, you should not specify an id manually. Instead the id will be derived from the file basename.
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 |
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 |
BugReportUrl | bugReportUrl() | string |
EnabledByDefault | isEnabledByDefault() | bool |
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", "Version": "1.0", "Website": "https://plasma.kde.org/" } }
- See also
- KAboutPerson::fromJSON()
- Since
- 5.1
Definition at line 81 of file kpluginmetadata.h.
Member Enumeration Documentation
◆ KPluginMetaDataOption
Options for creating a KPluginMetaData object.
- Since
- 5.91
Enumerator | |
---|---|
AllowEmptyMetaData | Plugins with empty metaData are considered invalid. |
Definition at line 111 of file kpluginmetadata.h.
Constructor & Destructor Documentation
◆ KPluginMetaData() [1/5]
KPluginMetaData::KPluginMetaData | ( | ) |
Creates an invalid KPluginMetaData instance.
Definition at line 114 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [2/5]
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 167 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [3/5]
KPluginMetaData::KPluginMetaData | ( | const QString & | pluginFile, |
KPluginMetaDataOption | option = KPluginMetaDataOption::DoNotAllowEmptyMetaData |
||
) |
Reads the plugin metadata from a plugin which can be loaded from file
.
Platform-specific library suffixes may be omitted since file
will be resolved using the same logic as QPluginLoader.
- See also
- QPluginLoader::setFileName()
Definition at line 132 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [4/5]
KPluginMetaData::KPluginMetaData | ( | const QJsonObject & | metaData, |
const QString & | fileName | ||
) |
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.
- Parameters
-
metaData the JSON metadata to use for this object pluginFile the file that the plugin can be loaded from
- Since
- 6.0
Definition at line 178 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [5/5]
KPluginMetaData::KPluginMetaData | ( | const KPluginMetaData & | other | ) |
Copy contructor.
Definition at line 119 of file kpluginmetadata.cpp.
◆ ~KPluginMetaData()
|
default |
Destructor.
Member Function Documentation
◆ authors()
QList<KAboutPerson> KPluginMetaData::authors | ( | ) | const |
- Returns
- the author(s) of this plugin.
◆ bugReportUrl()
QString KPluginMetaData::bugReportUrl | ( | ) | const |
- Returns
- the website where people can report a bug found in this plugin
- Since
- 5.99
◆ category()
QString KPluginMetaData::category | ( | ) | const |
- Returns
- the categories of this plugin (e.g. "playlist/skin").
◆ copyrightText()
QString KPluginMetaData::copyrightText | ( | ) | const |
- Returns
- a short copyright statement
- Since
- 5.18
◆ description()
QString KPluginMetaData::description | ( | ) | const |
- Returns
- a short description of the plugin.
◆ fileName()
QString KPluginMetaData::fileName | ( | ) | const |
- Returns
- the path to the plugin. When the KPluginMetaData(QJsonObject, QString) constructor is used, the string is not modified. Otherwise, the path is resolved using QPluginLoader. For static plugins the fileName is the namespace and pluginId concatenated
- Note
- 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.
◆ findPluginById()
|
static |
- Parameters
-
directory The directory to search for plugins. If a relative path is given for directory
, all entries of QCoreApplication::libraryPaths() will be checked withdirectory
appended as a subdirectory. If an absolute path is given only that directory will be searched.
- Note
- Check if the returned KPluginMetaData is valid before continuing to use it.
- Parameters
-
pluginId The Id of the plugin. The id should be the same as the filename, see KPluginMetaData::pluginId()
- Since
- 5.84
Definition at line 203 of file kpluginmetadata.cpp.
◆ findPlugins() [1/2]
|
static |
- Since
- 5.91
Definition at line 257 of file kpluginmetadata.cpp.
◆ findPlugins() [2/2]
|
static |
Find all plugins inside directory
.
Only plugins which have JSON metadata will be considered.
- Parameters
-
directory The directory to search for plugins. If a relative path is given for directory
, all entries of QCoreApplication::libraryPaths() will be checked withdirectory
appended as a subdirectory. If an absolute path is given only that directory will be searched.filter a callback function that returns true
if the found plugin should be loaded andfalse
if it should be skipped. If this argument is omitted all plugins will be loaded
- Returns
- all plugins found in
directory
that fulfil the constraints offilter
- Since
- 5.86
Definition at line 252 of file kpluginmetadata.cpp.
◆ formFactors()
QStringList KPluginMetaData::formFactors | ( | ) | const |
- Returns
- A string list of formfactors this plugin is useful for, e.g. desktop, handset or mediacenter. The keys for this are not formally defined, though the above-mentioned values should be used when applicable.
- Since
- 5.12
◆ fromJsonFile()
|
static |
Load a KPluginMetaData instance from a .json file.
Unlike the constructor with a single file argument, this ensure that only JSON format plugins are loaded and any other type is rejected.
- Parameters
-
jsonFile the .json file to load
- Since
- 5.91
Definition at line 225 of file kpluginmetadata.cpp.
◆ iconName()
QString KPluginMetaData::iconName | ( | ) | const |
- Returns
- the icon name for this plugin
- See also
- QIcon::fromTheme()
◆ isEnabled()
|
inline |
Returns true
if the plugin is enabled in config
, otherwise returns isEnabledByDefault().
This can be used in conjunction with KPluginWidget.
The config
param should be a KConfigGroup object, because KCoreAddons can not depend on KConfig directly, this parameter is a template.
- Parameters
-
config KConfigGroup where the enabled state is stored
- Since
- 5.89
Definition at line 354 of file kpluginmetadata.h.
◆ isEnabledByDefault()
bool KPluginMetaData::isEnabledByDefault | ( | ) | const |
- Returns
- whether the plugin should be enabled by default. This is only a recommendation, applications can ignore this value if they want to.
◆ isHidden()
bool KPluginMetaData::isHidden | ( | ) | const |
- Returns
- whether this object should be hidden
- Since
- 5.8
◆ isStaticPlugin()
bool KPluginMetaData::isStaticPlugin | ( | ) | const |
- Note
- for loading plugin the plugin independently of it being static/dynamic use KPluginFactory::loadFactory or KPluginFactory::instantiatePlugin.
- Returns
- true if the instance represents a static plugin
- Since
- 5.89
Definition at line 519 of file kpluginmetadata.cpp.
◆ isValid()
bool KPluginMetaData::isValid | ( | ) | const |
- Returns
- whether this object holds valid information about a plugin. If this is
true
pluginId() will return a non-empty string.
◆ license()
QString KPluginMetaData::license | ( | ) | const |
- Returns
- the short license identifier (e.g. LGPL).
- See also
- KAboutLicense::byKeyword() for retrieving the full license information
◆ licenseText()
QString KPluginMetaData::licenseText | ( | ) | const |
- Returns
- the text of the license, equivalent to KAboutLicense::byKeyword(license()).text()
- Since
- 5.73
◆ mimeTypes()
QStringList KPluginMetaData::mimeTypes | ( | ) | const |
- Returns
- a list of MIME types this plugin can handle (e.g. "application/pdf", "image/png", etc.)
- Since
- 5.16
◆ name()
QString KPluginMetaData::name | ( | ) | const |
- Returns
- the user visible name of the plugin.
◆ operator!=()
|
inline |
- Returns
true
if this object is not equal toother
, otherwisefalse
.
Definition at line 396 of file kpluginmetadata.h.
◆ operator=()
KPluginMetaData & KPluginMetaData::operator= | ( | const KPluginMetaData & | other | ) |
Copy assignment.
Definition at line 124 of file kpluginmetadata.cpp.
◆ operator==()
bool KPluginMetaData::operator== | ( | const KPluginMetaData & | other | ) | const |
- Returns
true
if this object is equal toother
, otherwisefalse
Definition at line 514 of file kpluginmetadata.cpp.
◆ otherContributors()
QList<KAboutPerson> KPluginMetaData::otherContributors | ( | ) | const |
- Returns
- a list of people that contributed to this plugin (other than the authors and translators).
- Since
- 5.18
◆ pluginId()
QString KPluginMetaData::pluginId | ( | ) | const |
- Returns
- the unique identifier within the namespace of the plugin
For C++ plugins, this ID is derived from the filename. It should not be set in the metadata explicitly.
When using KPluginMetaData::fromJsonFile or KPluginMetaData(QJsonObject, QString), the "Id" of the "KPlugin" object will be used. If unset, it will be derived from the filename.
◆ rawData()
QJsonObject KPluginMetaData::rawData | ( | ) | const |
- Returns
- the full metadata stored inside the plugin file.
◆ supportsMimeType()
bool KPluginMetaData::supportsMimeType | ( | const QString & | mimeType | ) | const |
- Returns
- 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.
- Since
- 5.66
Definition at line 406 of file kpluginmetadata.cpp.
◆ translators()
QList<KAboutPerson> KPluginMetaData::translators | ( | ) | const |
- Returns
- the translator(s) of this plugin.
- Since
- 5.18
◆ value() [1/4]
bool KPluginMetaData::value | ( | const QString & | key, |
bool | defaultValue | ||
) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
- Since
- 5.88
Definition at line 462 of file kpluginmetadata.cpp.
◆ value() [2/4]
QString KPluginMetaData::value | ( | const QString & | key, |
const QString & | defaultValue = QString() |
||
) | const |
- Returns
- the string value for
key
from the metadata ordefaultValue
if the key does not exist
if QString is not the correct type for key
you should use the other overloeads or KPluginMetaData::rawData
Definition at line 447 of file kpluginmetadata.cpp.
◆ value() [3/4]
QStringList KPluginMetaData::value | ( | const QString & | key, |
const QStringList & | defaultValue | ||
) | const |
- Returns
- the value for
key
from the metadata ordefaultValue
if the key does not exist. If the type ofkey
is string, a list containing just that string will be returned. If the type is array, the list will contain one entry for each array member. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
- Since
- 5.88
Definition at line 493 of file kpluginmetadata.cpp.
◆ value() [4/4]
int KPluginMetaData::value | ( | const QString & | key, |
int | defaultValue | ||
) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
- Since
- 5.88
Definition at line 474 of file kpluginmetadata.cpp.
◆ version()
QString KPluginMetaData::version | ( | ) | const |
- Returns
- the version of the plugin.
◆ website()
QString KPluginMetaData::website | ( | ) | const |
- Returns
- the website of the plugin.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Jun 6 2023 04:03:43 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.