KPluginMetaData Class Reference

#include <KPluginMetaData>

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< KAboutPerson >	authors () 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
QObject *	instantiate () const
bool	isEnabledByDefault () const
bool	isHidden () const
bool	isValid () const
QString	license () const
QString	metaDataFileName () 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
QStringList	serviceTypes () const
bool	supportsMimeType (const QString &mimeType) const
QList< KAboutPerson >	translators () const
QString	value (const QString &key, const QString &defaultValue=QString()) const
QString	version () const
QString	website () const

Static Public Member Functions
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",
     "Dependencies": [],
     "EnabledByDefault": "true",
     "License": "LGPL",
     "Id": "time",
     "Version": "1.0",
     "Website": "https://plasma.kde.org/",
     "ServiceTypes": ["Plasma/DataEngine"]
  }
}

See also

KAboutPerson::fromJSON()

Since

5.1

Definition at line 88 of file kpluginmetadata.h.

Constructor & Destructor Documentation

KPluginMetaData::KPluginMetaData

(

)

Creates an invalid KPluginMetaData instance.

Definition at line 30 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 84 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 78 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

QPluginLoader::setFileName()

KPluginMetaData::fromDesktopFile()

Definition at line 51 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 90 of file kpluginmetadata.cpp.

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 96 of file kpluginmetadata.cpp.

KPluginMetaData::KPluginMetaData

(

const KPluginMetaData &

other

)

Copy contructor.

Definition at line 34 of file kpluginmetadata.cpp.

KPluginMetaData::~KPluginMetaData

(

)

Destructor.

Definition at line 47 of file kpluginmetadata.cpp.

Member Function Documentation

QList< KAboutPerson > KPluginMetaData::authors

(

)

const

Returns

the author(s) of this plugin.

Definition at line 233 of file kpluginmetadata.cpp.

QString KPluginMetaData::category

(

)

const

Returns

the categories of this plugin (e.g. "playlist/skin").

Definition at line 248 of file kpluginmetadata.cpp.

QString KPluginMetaData::copyrightText

(

)

const

Returns

a short copyright statement

Since

5.18

Definition at line 273 of file kpluginmetadata.cpp.

QStringList KPluginMetaData::dependencies

(

)

const

Returns

a list of plugins that this plugin depends on so that it can function properly

See also

KJsonPluginInfo::pluginId()

Definition at line 310 of file kpluginmetadata.cpp.

QString KPluginMetaData::description

(

)

const

Returns

a short description of the plugin.

Definition at line 253 of file kpluginmetadata.cpp.

QString KPluginMetaData::extraInformation

(

)

const

Returns

additional information about this plugin (e.g. for use in an "about plugin" dialog)

Since

5.18

Definition at line 278 of file kpluginmetadata.cpp.

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.

Definition at line 136 of file kpluginmetadata.cpp.

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

Definition at line 340 of file kpluginmetadata.cpp.

KPluginMetaData KPluginMetaData::fromDesktopFile ( const QString &  file, const QStringList &  serviceTypes = QStringList()  )

static

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.

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

Definition at line 106 of file kpluginmetadata.cpp.

QString KPluginMetaData::iconName

(

)

const

Returns

the icon name for this plugin

See also

QIcon::fromTheme()

Definition at line 258 of file kpluginmetadata.cpp.

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

Definition at line 356 of file kpluginmetadata.cpp.

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

See also

QPluginLoader::instance(), KPluginLoader::instance()

Definition at line 387 of file kpluginmetadata.cpp.

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.

Definition at line 345 of file kpluginmetadata.cpp.

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

Definition at line 153 of file kpluginmetadata.cpp.

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.

Definition at line 147 of file kpluginmetadata.cpp.

QString KPluginMetaData::license

(

)

const

Returns

the short license identifier (e.g. LGPL).

See also

KAboutLicense::byKeyword() for retrieving the full license information

Definition at line 263 of file kpluginmetadata.cpp.

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

Definition at line 141 of file kpluginmetadata.cpp.

QStringList KPluginMetaData::mimeTypes

(

)

const

Returns

a list of MIME types this plugin can handle (e.g. "application/pdf", "image/png", etc.)

Since

5.16

Definition at line 320 of file kpluginmetadata.cpp.

QString KPluginMetaData::name

(

)

const

Returns

the user visible name of the plugin.

Definition at line 268 of file kpluginmetadata.cpp.

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

inline

Returns

true if this object is not equal to other, otherwise false.

Definition at line 400 of file kpluginmetadata.h.

KPluginMetaData & KPluginMetaData::operator=

(

const KPluginMetaData &

other

)

Copy assignment.

Definition at line 39 of file kpluginmetadata.cpp.

bool KPluginMetaData::operator==

(

const KPluginMetaData &

other

)

const

Returns

true if this object is equal to other, otherwise false

Definition at line 382 of file kpluginmetadata.cpp.

QList< KAboutPerson > KPluginMetaData::otherContributors

(

)

const

Returns

a list of people that contributed to this plugin (other than the authors and translators).

Since

5.18

Definition at line 243 of file kpluginmetadata.cpp.

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.

Definition at line 283 of file kpluginmetadata.cpp.

QJsonObject KPluginMetaData::rawData

(

)

const

Returns

the full metadata stored inside the plugin file.

Definition at line 131 of file kpluginmetadata.cpp.

QStringList KPluginMetaData::readStringList ( const QJsonObject &  jo, const QString &  key  )

static

Returns

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 163 of file kpluginmetadata.cpp.

QString KPluginMetaData::readTranslatedString ( const QJsonObject &  jo, const QString &  key, const QString &  defaultValue = QString()  )

static

Returns

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 202 of file kpluginmetadata.cpp.

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

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 from jo or defaultValue if key was not found

Definition at line 182 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.

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")

Definition at line 315 of file kpluginmetadata.cpp.

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 325 of file kpluginmetadata.cpp.

QList< KAboutPerson > KPluginMetaData::translators

(

)

const

Returns

the translator(s) of this plugin.

Since

5.18

Definition at line 238 of file kpluginmetadata.cpp.

QString KPluginMetaData::value	(	const QString &	key,
		const QString &	defaultValue = QString()
	)		const

Returns

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 361 of file kpluginmetadata.cpp.

QString KPluginMetaData::version

(

)

const

Returns

the version of the plugin.

Definition at line 300 of file kpluginmetadata.cpp.

QString KPluginMetaData::website

(

)

const

Returns

the website of the plugin.

Definition at line 305 of file kpluginmetadata.cpp.

---

The documentation for this class was generated from the following files:

• kpluginmetadata.h
• kpluginmetadata.cpp