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 */