File indexing completed on 2024-11-03 12:41:42
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2000 Torben Weis <weis@kde.org> 0004 SPDX-FileCopyrightText: 2006 David Faure <faure@kde.org> 0005 0006 SPDX-License-Identifier: LGPL-2.0-only 0007 */ 0008 0009 #ifndef KMIMETYPETRADER_H 0010 #define KMIMETYPETRADER_H 0011 0012 #include <kservice.h> 0013 class KMimeTypeTraderPrivate; 0014 class KServiceOffer; 0015 typedef QList<KServiceOffer> KServiceOfferList; 0016 0017 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 82) 0018 /** 0019 * @class KMimeTypeTrader kmimetypetrader.h <KMimeTypeTrader> 0020 * 0021 * KDE's trader for services associated to a given MIME type. 0022 * 0023 * Example: say that you want to the list of all KParts components that can handle HTML. 0024 * Our code would look like: 0025 * \code 0026 * KService::List lst = KMimeTypeTrader::self()->query("text/html", 0027 * "KParts/ReadOnlyPart"); 0028 * \endcode 0029 * 0030 * If you want to get the preferred KParts component for text/html you would use: 0031 * @code 0032 * KService::Ptr service = KMimeTypeTrader::self()->preferredService("text/html", 0033 * "KParts/ReadOnlyPart"); 0034 * @endcode 0035 * Although if this is about loading that component you would use createPartInstanceFromQuery() directly. 0036 * 0037 * @see KServiceTypeTrader, KService 0038 * 0039 * @deprecated since 5.82. For querying applications use KApplicationTrader. 0040 * For querying KParts use KParts::PartLoader. 0041 * For querying plugins use KPluginLoader. 0042 */ 0043 class KSERVICE_EXPORT KMimeTypeTrader 0044 { 0045 public: 0046 /** 0047 * Standard destructor 0048 */ 0049 ~KMimeTypeTrader(); 0050 0051 /** 0052 * This method returns a list of services which are associated with a given MIME type. 0053 * 0054 * Example usage: 0055 * To get list of applications that can handle a given MIME type, 0056 * set @p genericServiceType to "Application" (which is the default). 0057 * To get list of embeddable components that can handle a given MIME type, 0058 * set @p genericServiceType to "KParts/ReadOnlyPart". 0059 * 0060 * The constraint parameter is used to limit the possible choices 0061 * returned based on the constraints you give it. 0062 * 0063 * The @p constraint language is rather full. The most common 0064 * keywords are AND, OR, NOT, IN, and EXIST, all used in an 0065 * almost spoken-word form. An example is: 0066 * \code 0067 * (Type == 'Service') and (('Browser/View' in ServiceTypes) and (exist Library)) 0068 * \endcode 0069 * 0070 * The keys used in the query (Type, ServiceTypes, Library) are all 0071 * fields found in the .desktop files. 0072 * 0073 * @param mimeType a MIME type like 'text/plain' or 'text/html' 0074 * @param genericServiceType a basic service type, like 'KParts/ReadOnlyPart' or 'Application' 0075 * @param constraint A constraint to limit the choices returned, QString() to 0076 * get all services that can handle the given @p mimetype 0077 * 0078 * @return A list of services that satisfy the query, sorted by preference 0079 * (preferred service first) 0080 * @see http://techbase.kde.org/Development/Tutorials/Services/Traders#The_KTrader_Query_Language 0081 * @deprecated since 5.82. For querying applications use KApplicationTrader::query(). 0082 * For querying KParts use KParts::PartLoader::partsForMimeType(). 0083 * For querying plugins use KPluginLoader. 0084 */ 0085 KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.") 0086 KService::List 0087 query(const QString &mimeType, const QString &genericServiceType = QStringLiteral("Application"), const QString &constraint = QString()) const; 0088 0089 /** 0090 * Returns the preferred service for @p mimeType and @p genericServiceType 0091 * 0092 * This is almost like query().first(), except that it also checks 0093 * if the service is allowed as a preferred service (see KService::allowAsDefault). 0094 * 0095 * @param mimeType the MIME type (see query()) 0096 * @param genericServiceType the service type (see query()) 0097 * @return the preferred service, or @c nullptr if no service is available. 0098 * @deprecated since 5.82. For querying applications use KApplicationTrader::preferredService(). For querying KParts use 0099 * KParts::PartLoader::partsForMimeType().first(). 0100 */ 0101 KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.") 0102 KService::Ptr preferredService(const QString &mimeType, const QString &genericServiceType = QStringLiteral("Application")); 0103 0104 /** 0105 * This method creates and returns a part object from the trader query for a given \p mimeType. 0106 * 0107 * Example: 0108 * \code 0109 * KParts::ReadOnlyPart* part = KMimeTypeTrader::createPartInstanceFromQuery<KParts::ReadOnlyPart>("text/plain", parentWidget, parentObject); 0110 * if (part) { 0111 * part->openUrl(url); 0112 * part->widget()->show(); // also insert the widget into a layout 0113 * } 0114 * \endcode 0115 * 0116 * @param mimeType the MIME type which this part is associated with 0117 * @param parentWidget the parent widget, will be set as the parent of the part's widget 0118 * @param parent the parent object for the part itself 0119 * @param constraint an optional constraint to pass to the trader 0120 * @param args A list of arguments passed to the service component 0121 * @param error The string passed here will contain an error description. 0122 * @return A pointer to the newly created object or a null pointer if the 0123 * factory was unable to create an object of the given type. 0124 * @deprecated since 5.82. For KParts use KParts::PartLoader::createPartInstanceForMimeType(). 0125 * Otherwise use KPluginLoader. 0126 */ 0127 template<class T> 0128 KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.") 0129 static T *createPartInstanceFromQuery(const QString &mimeType, 0130 QWidget *parentWidget = nullptr, 0131 QObject *parent = nullptr, 0132 const QString &constraint = QString(), 0133 const QVariantList &args = QVariantList(), 0134 QString *error = nullptr) 0135 { 0136 const KService::List offers = self()->query(mimeType, QStringLiteral("KParts/ReadOnlyPart"), constraint); 0137 for (const KService::Ptr &ptr : offers) { 0138 T *component = ptr->template createInstance<T>(parentWidget, parent, args, error); 0139 if (component) { 0140 if (error) { 0141 error->clear(); 0142 } 0143 return component; 0144 } 0145 } 0146 if (error) { 0147 *error = QCoreApplication::translate("", "No service matching the requirements was found"); 0148 } 0149 return nullptr; 0150 } 0151 0152 /** 0153 * This can be used to create a service instance from a MIME type query. 0154 * 0155 * @param mimeType a MIME type like 'text/plain' or 'text/html' 0156 * @param serviceType a basic service type 0157 * @param parent the parent object for the plugin itself 0158 * @param constraint A constraint to limit the choices returned, QString() to 0159 * get all services that can handle the given @p mimeType 0160 * @param args A list of arguments passed to the service component 0161 * @param error The string passed here will contain an error description. 0162 * @return A pointer to the newly created object or a null pointer if the 0163 * factory was unable to create an object of the given type. 0164 * @deprecated since 5.82. For KParts use KParts::PartLoader::createPartInstanceForMimeType(). 0165 * Otherwise use KPluginLoader. 0166 */ 0167 template<class T> 0168 KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.") 0169 static T *createInstanceFromQuery(const QString &mimeType, 0170 const QString &serviceType, 0171 QObject *parent = nullptr, 0172 const QString &constraint = QString(), 0173 const QVariantList &args = QVariantList(), 0174 QString *error = nullptr) 0175 { 0176 const KService::List offers = self()->query(mimeType, serviceType, constraint); 0177 for (const KService::Ptr &ptr : offers) { 0178 T *component = ptr->template createInstance<T>(parent, args, error); 0179 if (component) { 0180 if (error) { 0181 error->clear(); 0182 } 0183 return component; 0184 } 0185 } 0186 if (error) { 0187 *error = QCoreApplication::translate("", "No service matching the requirements was found"); 0188 } 0189 return nullptr; 0190 } 0191 0192 /** 0193 * This is a static pointer to the KMimeTypeTrader singleton. 0194 * 0195 * You will need to use this to access the KMimeTypeTrader functionality since the 0196 * constructors are protected. 0197 * 0198 * @return Static KMimeTypeTrader instance 0199 */ 0200 static KMimeTypeTrader *self(); 0201 0202 private: 0203 /** 0204 * @internal 0205 */ 0206 KMimeTypeTrader(); 0207 0208 private: 0209 KMimeTypeTraderPrivate *const d; 0210 0211 // class-static so that it can access KSycocaEntry::offset() 0212 static void filterMimeTypeOffers(KServiceOfferList &list, const QString &genericServiceType); 0213 static void filterMimeTypeOffers(KService::List &list, const QString &genericServiceType); 0214 friend class KMimeTypeTraderSingleton; 0215 }; 0216 0217 #endif 0218 0219 #endif /* KMIMETYPETRADER_H */