1/* This file is part of the KDE libraries
2 Copyright (C) 2000 Torben Weis <weis@kde.org>
3 Copyright (C) 2006 David Faure <faure@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KMIMETYPETRADER_H
21#define KMIMETYPETRADER_H
22
23#include <kservice.h>
24class KServiceOffer;
25
26/**
27 * KDE's trader for services associated to a given mimetype.
28 *
29 * Example: say that you want to the list of all KParts components that can handle HTML.
30 * Our code would look like:
31 * \code
32 * KService::List lst = KMimeTypeTrader::self()->query("text/html",
33 * "KParts/ReadOnlyPart");
34 * \endcode
35 *
36 * If you want to get the preferred KParts component for text/html you could use
37 * preferredService("text/html", "KParts/ReadOnlyPart"), although if this is about
38 * loading that component you would use createPartInstanceFromQuery directly.
39 *
40 * @see KServiceTypeTrader, KService
41 */
42class KDECORE_EXPORT KMimeTypeTrader
43{
44public:
45
46 /**
47 * Standard destructor
48 */
49 ~KMimeTypeTrader();
50
51 /**
52 * This method returns a list of services which are associated with a given mimetype.
53 *
54 * Example usage:
55 * To get list of applications that can handle a given mimetype,
56 * set @p genericServiceType to "Application" (which is the default).
57 * To get list of embeddable components that can handle a given mimetype,
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 */
82 KService::List query( const QString& mimeType,
83 const QString& genericServiceType = QString::fromLatin1("Application"),
84 const QString& constraint = QString() ) const;
85
86
87 /**
88 * Returns the preferred service for @p mimeType and @p genericServiceType
89 *
90 * This is almost like query().first(), except that it also checks
91 * if the service is allowed as a preferred service (see KService::allowAsDefault).
92 *
93 * @param mimeType the mime type (see query())
94 * @param genericServiceType the service type (see query())
95 * @return the preferred service, or 0 if no service is available
96 */
97 KService::Ptr preferredService( const QString & mimeType, const QString & genericServiceType = QString::fromLatin1("Application") );
98
99 /**
100 * This method creates and returns a part object from the trader query for a given \p mimeType.
101 *
102 * Example:
103 * \code
104 * KParts::ReadOnlyPart* part = KMimeTypeTrader::createInstanceFromQuery<KParts::ReadOnlyPart>("text/plain", parentWidget, parentObject);
105 * if (part) {
106 * part->openUrl(url);
107 * part->widget()->show(); // also insert the widget into a layout, or simply use a KVBox as parentWidget
108 * }
109 * \endcode
110 *
111 * @param mimeType the mimetype which this part is associated with
112 * @param parentWidget the parent widget, will be set as the parent of the part's widget
113 * @param parent the parent object for the part itself
114 * @param constraint an optional constraint to pass to the trader
115 * @param args A list of arguments passed to the service component
116 * @param error The string passed here will contain an error description.
117 * @return A pointer to the newly created object or a null pointer if the
118 * factory was unable to create an object of the given type.
119 */
120 template <class T>
121 static T *createPartInstanceFromQuery(const QString &mimeType, QWidget *parentWidget = 0, QObject *parent = 0,
122 const QString &constraint = QString(),
123 const QVariantList &args = QVariantList(),
124 QString *error = 0)
125 {
126 const KService::List offers = self()->query(mimeType, QString::fromLatin1("KParts/ReadOnlyPart"), constraint);
127 Q_FOREACH (const KService::Ptr &ptr, offers) {
128 T *component = ptr->template createInstance<T>(parentWidget, parent, args, error);
129 if (component) {
130 if (error)
131 error->clear();
132 return component;
133 }
134 }
135 if (error)
136 *error = i18n("No service matching the requirements was found");
137 return 0;
138 }
139
140 /**
141 * This can be used to create a service instance from a mime type query
142 *
143 * @param mimeType A mime type like 'text/plain' or 'text/html'.
144 * @param serviceType a basic service type
145 * @param parent the parent object for the plugin itself
146 * @param constraint A constraint to limit the choices returned, QString() to
147 * get all services that can handle the given @p mimetype
148 * @param args A list of arguments passed to the service component
149 * @param error The string passed here will contain an error description.
150 * @return A pointer to the newly created object or a null pointer if the
151 * factory was unable to create an object of the given type.
152 */
153 template <class T>
154 static T *createInstanceFromQuery(const QString &mimeType, const QString &serviceType, QObject *parent = 0,
155 const QString &constraint = QString(),
156 const QVariantList &args = QVariantList(),
157 QString *error = 0)
158 {
159 const KService::List offers = self()->query(mimeType, serviceType, constraint);
160 Q_FOREACH (const KService::Ptr &ptr, offers) {
161 T *component = ptr->template createInstance<T>(parent, args, error);
162 if (component) {
163 if (error)
164 error->clear();
165 return component;
166 }
167 }
168 if (error)
169 *error = i18n("No service matching the requirements was found");
170 return 0;
171 }
172
173 /**
174 * This is a static pointer to the KMimeTypeTrader singleton.
175 *
176 * You will need to use this to access the KMimeTypeTrader functionality since the
177 * constructors are protected.
178 *
179 * @return Static KMimeTypeTrader instance
180 */
181 static KMimeTypeTrader* self();
182
183private:
184 /**
185 * @internal
186 */
187 KMimeTypeTrader();
188
189private:
190 class Private;
191 Private * const d;
192};
193
194#endif /* KMIMETYPETRADER_H */
195