KPluginMetaData
#include <KPluginMetaData>

Public Types | |
enum | KPluginMetaDataOption { DoNotAllowEmptyMetaData, AllowEmptyMetaData } |
Properties | |
QVariantList | authors |
QString | bugReportUrl |
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 |
Static Public Member Functions | |
static KPluginMetaData | findPluginById (const QString &directory, const QString &pluginId) |
static QVector< KPluginMetaData > | findPlugins (const QString &directory, std::function< bool(const KPluginMetaData &)> filter, KPluginMetaDataOption option) |
static QVector< KPluginMetaData > | findPlugins (const QString &directory, std::function< bool(const KPluginMetaData &)> filter={}) |
static KPluginMetaData | fromDesktopFile (const QString &file, const QStringList &serviceTypes=QStringList()) |
static KPluginMetaData | fromJsonFile (const QString &jsonFile) |
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 |
BugReportUrl | bugReportUrl() | 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": "https://plasma.kde.org/" } }
- See also
- KAboutPerson::fromJSON()
- Since
- 5.1
Definition at line 87 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 128 of file kpluginmetadata.h.
Constructor & Destructor Documentation
◆ KPluginMetaData() [1/8]
KPluginMetaData::KPluginMetaData | ( | ) |
Creates an invalid KPluginMetaData instance.
Definition at line 115 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [2/8]
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 186 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [3/8]
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 180 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [4/8]
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.
- Note
- Using this constructor for metadata files is deprecated.. Use KPluginMetaData::fromDesktopFile or KPluginMetaData::fromJsonFile instead.
- See also
- QPluginLoader::setFileName()
- KPluginMetaData::fromDesktopFile()
- KPluginMetaData::fromJsonFile()
Definition at line 139 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [5/8]
KPluginMetaData::KPluginMetaData | ( | const QString & | file, |
KPluginMetaDataOption | option | ||
) |
Overload which takes an option parameter that gets used when creating the KPluginMetaData instances.
- Since
- 5.91
Definition at line 144 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [6/8]
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.
Definition at line 192 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [7/8]
KPluginMetaData::KPluginMetaData | ( | const QJsonObject & | metaData, |
const QString & | pluginFile, | ||
const QString & | metaDataFile | ||
) |
Creates a KPluginMetaData.
- Parameters
-
metaData the JSON metadata to use for this object pluginFile the file that the plugin can be loaded from metaDataFile the 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.
- Since
- 5.5
Definition at line 197 of file kpluginmetadata.cpp.
◆ KPluginMetaData() [8/8]
KPluginMetaData::KPluginMetaData | ( | const KPluginMetaData & | other | ) |
Copy contructor.
Definition at line 120 of file kpluginmetadata.cpp.
◆ ~KPluginMetaData()
KPluginMetaData::~KPluginMetaData | ( | ) |
Destructor.
Definition at line 135 of file kpluginmetadata.cpp.
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
◆ dependencies()
QStringList KPluginMetaData::dependencies | ( | ) | const |
- Returns
- a list of plugins that this plugin depends on so that it can function properly
- See also
- KJsonPluginInfo::pluginId()
- Deprecated:
- Since 5.79, plugin dependencies are deprecated and will be removed in KF6
◆ description()
QString KPluginMetaData::description | ( | ) | const |
- Returns
- a short description of the plugin.
◆ extraInformation()
QString KPluginMetaData::extraInformation | ( | ) | const |
- Returns
- additional information about this plugin (e.g. for use in an "about plugin" dialog)
- Since
- 5.18
- Deprecated:
- Since 5.87, deprecate for lack of usage. Use a meaningful custom key in the json metadata instead
◆ fileName()
QString KPluginMetaData::fileName | ( | ) | const |
- Returns
- the path to the plugin. This string can be passed to the KPluginLoader or QPluginLoader constructors in order to attempt to load this plugin.
- 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 213 of file kpluginmetadata.cpp.
◆ findPlugins() [1/2]
|
static |
- Since
- 5.91
Definition at line 312 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 306 of file kpluginmetadata.cpp.
◆ formFactors()
QStringList KPluginMetaData::formFactors | ( | ) | const |
- Returns
- 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.
- Since
- 5.12
◆ fromDesktopFile()
|
static |
Load a KPluginMetaData instance 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.
- Note
- 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.
- Parameters
-
file the .desktop file to load serviceTypes a 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.
- Since
- 5.16
- Deprecated:
- Since 5.92, use json files or embedded json metadata directly.
Definition at line 239 of file kpluginmetadata.cpp.
◆ 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 284 of file kpluginmetadata.cpp.
◆ iconName()
QString KPluginMetaData::iconName | ( | ) | const |
- Returns
- the icon name for this plugin
- See also
- QIcon::fromTheme()
◆ initialPreference()
int KPluginMetaData::initialPreference | ( | ) | const |
- Returns
- 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.
- Since
- 5.67
◆ instantiate()
QObject * KPluginMetaData::instantiate | ( | ) | const |
Tries to instantiate this plugin using KPluginMetaData::fileName().
- Note
- The value of KPluginMetaData::dependencies() is not used here, dependencies must be resolved manually.
- Returns
- The plugin root object or
nullptr
if it could not be loaded
- Deprecated:
- Since 5.86, use KPluginFactory::loadFactory or KPluginFactory::instantiatePlugin when using KPluginFactory. Otherwise use QPluginLoader::instance() instead.
Definition at line 656 of file kpluginmetadata.cpp.
◆ isEnabled()
|
inline |
Returns true
if the plugin is enabled in config
, otherwise returns isEnabledByDefault().
This can be used in conjunctionwith KPluginWidget/KPluginSelector.
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 509 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, 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.
- 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 692 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
◆ metaDataFileName()
QString KPluginMetaData::metaDataFileName | ( | ) | const |
- Returns
- 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.
- Since
- 5.5
◆ 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 600 of file kpluginmetadata.h.
◆ operator=()
KPluginMetaData & KPluginMetaData::operator= | ( | const KPluginMetaData & | other | ) |
Copy assignment.
Definition at line 127 of file kpluginmetadata.cpp.
◆ operator==()
bool KPluginMetaData::operator== | ( | const KPluginMetaData & | other | ) | const |
- Returns
true
if this object is equal toother
, otherwisefalse
Definition at line 650 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 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.
◆ rawData()
QJsonObject KPluginMetaData::rawData | ( | ) | const |
- Returns
- the full metadata stored inside the plugin file.
◆ readStringList()
|
static |
- Returns
- the value for
key
insidejo
as a string list. If the type ofkey
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.
- Deprecated:
- Since 5.88, use
value(QString, QStringList)
on KPluginMetaData instance instead
Definition at line 363 of file kpluginmetadata.cpp.
◆ readTranslatedString()
|
static |
- Returns
- the translated value of
key
fromjo
as a string ordefaultValue
ifkey
was not found or the value forkey
is not of type string
- See also
- KPluginMetaData::readTranslatedValue(const QJsonObject &jo, const QString &key)
- Deprecated:
- Since 5.88, use KJsonUtils::readTranslatedString instead
Definition at line 389 of file kpluginmetadata.cpp.
◆ readTranslatedValue()
|
static |
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.
- Returns
- the translated value for
key
fromjo
ordefaultValue
ifkey
was not found
- Deprecated:
- Since 5.88, use KJsonUtils::readTranslatedValue instead
Definition at line 384 of file kpluginmetadata.cpp.
◆ serviceTypes()
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.
- Note
- Unlike KService this does not contain the MIME types. To get the handled MIME types use the KPluginMetaData::mimeTypes() function.
- Returns
- a list of service types this plugin implements (e.g. "Plasma/DataEngine") @dprecated Since 5.89, use dedicated plugin namespaces instead to filter plugins of a specific type
◆ 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 530 of file kpluginmetadata.cpp.
◆ translators()
QList<KAboutPerson> KPluginMetaData::translators | ( | ) | const |
- Returns
- the translator(s) of this plugin.
- Since
- 5.18
◆ value() [1/5]
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 597 of file kpluginmetadata.cpp.
◆ value() [2/5]
Overload to make sure the bool overload is not taken by accident 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 530 of file kpluginmetadata.h.
◆ value() [3/5]
QString KPluginMetaData::value | ( | const QString & | key, |
const QString & | defaultValue = QString() |
||
) | const |
- Returns
- the value for
key
from the metadata ordefaultValue
if the key does not exist or the value forkey
is not of type string
- See also
- KPluginMetaData::rawData() if QString is not the correct type for
key
Definition at line 574 of file kpluginmetadata.cpp.
◆ value() [4/5]
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 628 of file kpluginmetadata.cpp.
◆ value() [5/5]
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 609 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 Fri Feb 3 2023 04:16:50 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.