KService

kmimetypetrader.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Torben Weis <[email protected]>
4  SPDX-FileCopyrightText: 2006 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef KMIMETYPETRADER_H
10 #define KMIMETYPETRADER_H
11 
12 #include <kservice.h>
13 class KMimeTypeTraderPrivate;
14 class KServiceOffer;
16 
17 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 82)
18 /**
19  * @class KMimeTypeTrader kmimetypetrader.h <KMimeTypeTrader>
20  *
21  * KDE's trader for services associated to a given MIME type.
22  *
23  * Example: say that you want to the list of all KParts components that can handle HTML.
24  * Our code would look like:
25  * \code
26  * KService::List lst = KMimeTypeTrader::self()->query("text/html",
27  * "KParts/ReadOnlyPart");
28  * \endcode
29  *
30  * If you want to get the preferred KParts component for text/html you would use:
31  * @code
32  * KService::Ptr service = KMimeTypeTrader::self()->preferredService("text/html",
33  * "KParts/ReadOnlyPart");
34  * @endcode
35  * Although if this is about loading that component you would use createPartInstanceFromQuery() directly.
36  *
37  * @see KServiceTypeTrader, KService
38  *
39  * @deprecated since 5.82. For querying applications use KApplicationTrader.
40  * For querying KParts use KParts::PartLoader.
41  * For querying plugins use KPluginLoader.
42  */
43 class KSERVICE_EXPORT KMimeTypeTrader
44 {
45 public:
46  /**
47  * Standard destructor
48  */
49  ~KMimeTypeTrader();
50 
51  /**
52  * This method returns a list of services which are associated with a given MIME type.
53  *
54  * Example usage:
55  * To get list of applications that can handle a given MIME type,
56  * set @p genericServiceType to "Application" (which is the default).
57  * To get list of embeddable components that can handle a given MIME type,
58  * set @p genericServiceType to "KParts/ReadOnlyPart".
59  *
60  * The constraint parameter is used to limit the possible choices
61  * returned based on the constraints you give it.
62  *
63  * The @p constraint language is rather full. The most common
64  * keywords are AND, OR, NOT, IN, and EXIST, all used in an
65  * almost spoken-word form. An example is:
66  * \code
67  * (Type == 'Service') and (('Browser/View' in ServiceTypes) and (exist Library))
68  * \endcode
69  *
70  * The keys used in the query (Type, ServiceTypes, Library) are all
71  * fields found in the .desktop files.
72  *
73  * @param mimeType a MIME type like 'text/plain' or 'text/html'
74  * @param genericServiceType a basic service type, like 'KParts/ReadOnlyPart' or 'Application'
75  * @param constraint A constraint to limit the choices returned, QString() to
76  * get all services that can handle the given @p mimetype
77  *
78  * @return A list of services that satisfy the query, sorted by preference
79  * (preferred service first)
80  * @see http://techbase.kde.org/Development/Tutorials/Services/Traders#The_KTrader_Query_Language
81  * @deprecated since 5.82. For querying applications use KApplicationTrader::query().
82  * For querying KParts use KParts::PartLoader::partsForMimeType().
83  * For querying plugins use KPluginLoader.
84  */
85  KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.")
87  query(const QString &mimeType, const QString &genericServiceType = QStringLiteral("Application"), const QString &constraint = QString()) const;
88 
89  /**
90  * Returns the preferred service for @p mimeType and @p genericServiceType
91  *
92  * This is almost like query().first(), except that it also checks
93  * if the service is allowed as a preferred service (see KService::allowAsDefault).
94  *
95  * @param mimeType the MIME type (see query())
96  * @param genericServiceType the service type (see query())
97  * @return the preferred service, or @c nullptr if no service is available.
98  * @deprecated since 5.82. For querying applications use KApplicationTrader::preferredService(). For querying KParts use
99  * KParts::PartLoader::partsForMimeType().first().
100  */
101  KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.")
102  KService::Ptr preferredService(const QString &mimeType, const QString &genericServiceType = QStringLiteral("Application"));
103 
104  /**
105  * This method creates and returns a part object from the trader query for a given \p mimeType.
106  *
107  * Example:
108  * \code
109  * KParts::ReadOnlyPart* part = KMimeTypeTrader::createPartInstanceFromQuery<KParts::ReadOnlyPart>("text/plain", parentWidget, parentObject);
110  * if (part) {
111  * part->openUrl(url);
112  * part->widget()->show(); // also insert the widget into a layout
113  * }
114  * \endcode
115  *
116  * @param mimeType the MIME type which this part is associated with
117  * @param parentWidget the parent widget, will be set as the parent of the part's widget
118  * @param parent the parent object for the part itself
119  * @param constraint an optional constraint to pass to the trader
120  * @param args A list of arguments passed to the service component
121  * @param error The string passed here will contain an error description.
122  * @return A pointer to the newly created object or a null pointer if the
123  * factory was unable to create an object of the given type.
124  * @deprecated since 5.82. For KParts use KParts::PartLoader::createPartInstanceForMimeType().
125  * Otherwise use KPluginLoader.
126  */
127  template<class T>
128  KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.")
129  static T *createPartInstanceFromQuery(const QString &mimeType,
130  QWidget *parentWidget = nullptr,
131  QObject *parent = nullptr,
132  const QString &constraint = QString(),
133  const QVariantList &args = QVariantList(),
134  QString *error = nullptr)
135  {
136  const KService::List offers = self()->query(mimeType, QStringLiteral("KParts/ReadOnlyPart"), constraint);
137  for (const KService::Ptr &ptr : offers) {
138  T *component = ptr->template createInstance<T>(parentWidget, parent, args, error);
139  if (component) {
140  if (error) {
141  error->clear();
142  }
143  return component;
144  }
145  }
146  if (error) {
147  *error = QCoreApplication::translate("", "No service matching the requirements was found");
148  }
149  return nullptr;
150  }
151 
152  /**
153  * This can be used to create a service instance from a MIME type query.
154  *
155  * @param mimeType a MIME type like 'text/plain' or 'text/html'
156  * @param serviceType a basic service type
157  * @param parent the parent object for the plugin itself
158  * @param constraint A constraint to limit the choices returned, QString() to
159  * get all services that can handle the given @p mimeType
160  * @param args A list of arguments passed to the service component
161  * @param error The string passed here will contain an error description.
162  * @return A pointer to the newly created object or a null pointer if the
163  * factory was unable to create an object of the given type.
164  * @deprecated since 5.82. For KParts use KParts::PartLoader::createPartInstanceForMimeType().
165  * Otherwise use KPluginLoader.
166  */
167  template<class T>
168  KSERVICE_DEPRECATED_VERSION(5, 82, "See API docs.")
169  static T *createInstanceFromQuery(const QString &mimeType,
170  const QString &serviceType,
171  QObject *parent = nullptr,
172  const QString &constraint = QString(),
173  const QVariantList &args = QVariantList(),
174  QString *error = nullptr)
175  {
176  const KService::List offers = self()->query(mimeType, serviceType, constraint);
177  for (const KService::Ptr &ptr : offers) {
178  T *component = ptr->template createInstance<T>(parent, args, error);
179  if (component) {
180  if (error) {
181  error->clear();
182  }
183  return component;
184  }
185  }
186  if (error) {
187  *error = QCoreApplication::translate("", "No service matching the requirements was found");
188  }
189  return nullptr;
190  }
191 
192  /**
193  * This is a static pointer to the KMimeTypeTrader singleton.
194  *
195  * You will need to use this to access the KMimeTypeTrader functionality since the
196  * constructors are protected.
197  *
198  * @return Static KMimeTypeTrader instance
199  */
200  static KMimeTypeTrader *self();
201 
202 private:
203  /**
204  * @internal
205  */
206  KMimeTypeTrader();
207 
208 private:
209  KMimeTypeTraderPrivate *const d;
210 
211  // class-static so that it can access KSycocaEntry::offset()
212  static void filterMimeTypeOffers(KServiceOfferList &list, const QString &genericServiceType);
213  static void filterMimeTypeOffers(KService::List &list, const QString &genericServiceType);
214  friend class KMimeTypeTraderSingleton;
215 };
216 
217 #endif
218 
219 #endif /* KMIMETYPETRADER_H */
QString translate(const char *context, const char *sourceText, const char *disambiguation, int n)
Holds the user's preference of a service.
Definition: kserviceoffer.h:30
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Nov 27 2022 03:56:45 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.