KParts

partloader.h
1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2020 David Faure <faure@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPARTS_PARTLOADER_H
9#define KPARTS_PARTLOADER_H
10
11#include <KPluginFactory>
12#include <KPluginMetaData>
13#include <QList>
14#include <QObject>
15#include <kparts/kparts_export.h>
16
17namespace KParts
18{
19Q_NAMESPACE_EXPORT(KPARTS_EXPORT)
20
21/**
22 * Enum for standardized capabilities of KParts
23 *
24 * @code
25 * {
26 * "KPlugin": {...},
27 * "KParts": {
28 * "Capabilities": [
29 * "ReadOnly"
30 * ],
31 * "InitialPreference": 42
32 * }
33 * }
34 * @endcode
35 *
36 * @since 6.4
37 */
38enum class PartCapability {
39 ReadOnly = 1,
40 ReadWrite = 2,
41 BrowserView = 4,
42};
43Q_ENUM_NS(PartCapability)
44Q_DECLARE_FLAGS(PartCapabilities, PartCapability)
45Q_FLAG_NS(PartCapabilities)
46Q_DECLARE_OPERATORS_FOR_FLAGS(PartCapabilities)
47
48/**
49 * Helper methods for locating and loading parts.
50 * This is based upon KPluginFactory, but it takes
51 * care of querying by mimetype, sorting the available parts by builtin
52 * preference and by user preference.
53 * @since 5.69
54 */
55namespace PartLoader
56{
57namespace Private
58{
59
60enum ErrorType {
61 CouldNotLoadPlugin,
62 NoPartFoundForMimeType,
63 NoPartInstantiatedForMimeType,
64};
65
66/**
67 * @internal
68 * @param errorString translated, user-visible error string
69 * @param errorText untranslated error text
70 * @param argument argument for the text
71 */
72KPARTS_EXPORT void getErrorStrings(QString *errorString, QString *errorText, const QString &argument, ErrorType type);
73
74}
75
76/**
77 * Parses the associated capabilities from the KPart. This parses the deprecated "ServiceTypes" array of the "KPlugin" object
78 *
79 * @since 6.4
80 */
81KPARTS_EXPORT PartCapabilities partCapabilities(const KPluginMetaData &data);
82
83/**
84 * Locate all available KParts using KPluginMetaData::findPlugins for a mimetype.
85 * @return a list of plugin metadata, sorted by preference.
86 * This takes care both of the builtin preference (set by developers)
87 * and of user preference (stored in mimeapps.list).
88 *
89 * To load a part from one of the KPluginMetaData instances returned here,
90 * use \ref instantiatePart()
91 *
92 * @since 5.69
93 */
94KPARTS_EXPORT QList<KPluginMetaData> partsForMimeType(const QString &mimeType);
95
96/**
97 * Attempts to create a KPart from the given metadata.
98 *
99 * @code
100 * if (auto result = KParts::PartLoader::instantiatePart<MyPart>(metaData, parentWidget, parent, args)) {
101 * // result.plugin is valid and can be accessed
102 * } else {
103 * // result contains information about the error
104 * }
105 * @endcode
106 * @param data KPluginMetaData from which the plugin should be loaded
107 * @param parentWidget The parent widget
108 * @param parent The parent object
109 * @param args A list of arguments to be passed to the part
110 * @return Result object which contains the plugin instance and potentially error information
111 * @since 5.100
112 */
113template<typename T>
115instantiatePart(const KPluginMetaData &data, QWidget *parentWidget = nullptr, QObject *parent = nullptr, const QVariantList &args = {})
116{
118 KPluginFactory::Result<KPluginFactory> factoryResult = KPluginFactory::loadFactory(data);
119 if (!factoryResult.plugin) {
120 result.errorString = factoryResult.errorString;
121 result.errorReason = factoryResult.errorReason;
122 return result;
123 }
124 T *instance = factoryResult.plugin->create<T>(parentWidget, parent, args);
125 if (!instance) {
126 const QString fileName = data.fileName();
127 Private::getErrorStrings(&result.errorString, &result.errorText, fileName, Private::CouldNotLoadPlugin);
128 result.errorReason = KPluginFactory::INVALID_KPLUGINFACTORY_INSTANTIATION;
129 } else {
130 result.plugin = instance;
131 }
132 return result;
133}
134
135/**
136 * Use this method to create a KParts part. It will try to create an object which inherits
137 * @p T.
138 *
139 * @code
140 * if (auto result = KParts::PartLoader::instantiatePartForMimeType<KParts::ReadOnlyPart>(mimeType, parentWidget, parent, args)) {
141 * // result.plugin is valid and can be accessed
142 * } else {
143 * // result contains information about the error
144 * }
145 * @endcode
146 *
147 * @tparam T The interface for which an object should be created. The object will inherit @p T.
148 * @param mimeType The mimetype for which we need a KParts.
149 * @param parentWidget The parent widget for the part's widget.
150 * @param parent The parent of the part.
151 * @return Result object which contains the plugin instance and potentially error information
152 * @since 5.100
153 */
154template<class T>
156instantiatePartForMimeType(const QString &mimeType, QWidget *parentWidget = nullptr, QObject *parent = nullptr, const QVariantList &args = {})
157{
159 if (plugins.isEmpty()) {
160 KPluginFactory::Result<T> errorResult;
161 errorResult.errorReason = KPluginFactory::ResultErrorReason::INVALID_PLUGIN;
162 Private::getErrorStrings(&errorResult.errorString, &errorResult.errorText, mimeType, Private::NoPartFoundForMimeType);
163
164 return errorResult;
165 }
166
167 for (const KPluginMetaData &plugin : plugins) {
168 if (const auto result = instantiatePart<T>(plugin, parentWidget, parent, args)) {
169 return result;
170 }
171 }
172
173 KPluginFactory::Result<T> errorResult;
174 errorResult.errorReason = KPluginFactory::ResultErrorReason::INVALID_PLUGIN;
175 Private::getErrorStrings(&errorResult.errorString, &errorResult.errorText, mimeType, Private::NoPartInstantiatedForMimeType);
176
177 return errorResult;
178}
179
180} // namespace
181} // namespace
182
183Q_DECLARE_METATYPE(KParts::PartCapabilities)
184
185#endif
QString fileName() const
static KPluginFactory::Result< T > instantiatePartForMimeType(const QString &mimeType, QWidget *parentWidget=nullptr, QObject *parent=nullptr, const QVariantList &args={})
Use this method to create a KParts part.
Definition partloader.h:156
KPARTS_EXPORT PartCapabilities partCapabilities(const KPluginMetaData &data)
Parses the associated capabilities from the KPart.
KPARTS_EXPORT QList< KPluginMetaData > partsForMimeType(const QString &mimeType)
Locate all available KParts using KPluginMetaData::findPlugins for a mimetype.
static KPluginFactory::Result< T > instantiatePart(const KPluginMetaData &data, QWidget *parentWidget=nullptr, QObject *parent=nullptr, const QVariantList &args={})
Attempts to create a KPart from the given metadata.
Definition partloader.h:115
The KParts namespace,.
PartCapability
Enum for standardized capabilities of KParts.
Definition partloader.h:38
bool isEmpty() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 21 2024 12:05:36 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.