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> |
24 | class 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 | */ |
42 | class KDECORE_EXPORT KMimeTypeTrader |
43 | { |
44 | public: |
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 | |
183 | private: |
184 | /** |
185 | * @internal |
186 | */ |
187 | KMimeTypeTrader(); |
188 | |
189 | private: |
190 | class Private; |
191 | Private * const d; |
192 | }; |
193 | |
194 | #endif /* KMIMETYPETRADER_H */ |
195 | |