1/* This file is part of the KDE project
2 Copyright (C) 2001 Simon Hausmann <hausmann@kde.org>
3 Copyright (C) 2002-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 as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20#ifndef KPARTS_COMPONENTFACTORY_H
21#define KPARTS_COMPONENTFACTORY_H
22
23#include <kparts/factory.h>
24#include <kparts/part.h>
25#include <kservicetypetrader.h>
26#ifndef KDE_NO_DEPRECATED
27#include <klibloader.h>
28#endif
29#include <kmimetypetrader.h>
30
31#include <QtCore/QFile>
32
33namespace KParts
34{
35 namespace ComponentFactory
36 {
37 /**
38 * This template function allows to ask the given kparts factory to
39 * create an instance of the given template type.
40 *
41 * Example of usage:
42 * \code
43 * KViewPart *doc = KParts::ComponentFactory::createPartInstanceFromFactory&lt;KViewPart&gt;( factory, parent );
44 * \endcode
45 *
46 * @deprecated use KPluginFactory::create instead
47 *
48 * @param factory The factory to ask for the creation of the component
49 * @param parentWidget the parent widget for the part
50 * @param parent The parent object (see QObject constructor)
51 * @param args A list of string arguments, passed to the factory and possibly
52 * to the component (see KLibFactory)
53 * @return A pointer to the newly created object or a null pointer if the
54 * factory was unable to create an object of the given type.
55 */
56#ifndef KDE_NO_DEPRECATED
57 template <class T>
58 KDE_DEPRECATED T *createPartInstanceFromFactory( KParts::Factory *factory,
59 QWidget *parentWidget = 0,
60 QObject *parent = 0,
61 const QStringList &args = QStringList() )
62 {
63 KParts::Part *object = factory->createPart( parentWidget,
64 parent,
65 T::staticMetaObject.className(),
66 args );
67
68 T *result = dynamic_cast<T *>( object );
69 if ( !result )
70 delete object;
71 return result;
72 }
73#endif
74
75 /*
76 * @deprecated use KPluginFactory::create instead
77 */
78#ifndef KDE_NO_DEPRECATED
79 template <class T>
80 KDE_DEPRECATED T *createPartInstanceFromLibrary( const char *libraryName,
81 QWidget *parentWidget = 0,
82 QObject *parent = 0,
83 const QStringList &args = QStringList(),
84 int *error = 0 )
85 {
86 KLibrary *library = KLibLoader::self()->library( QFile::decodeName( libraryName ) ); // compatibility hack
87 if ( !library )
88 {
89 if ( error )
90 *error = KLibLoader::ErrNoLibrary;
91 return 0;
92 }
93 KLibFactory *factory = library->factory();
94 if ( !factory )
95 {
96 library->unload();
97 if ( error )
98 *error = KLibLoader::ErrNoFactory;
99 return 0;
100 }
101 KParts::Factory *partFactory = dynamic_cast<KParts::Factory *>( factory );
102 if ( !partFactory )
103 {
104 library->unload();
105 if ( error )
106 *error = KLibLoader::ErrNoFactory;
107 return 0;
108 }
109 T *res = createPartInstanceFromFactory<T>( partFactory, parentWidget,
110 parent, args );
111 if ( !res )
112 {
113 library->unload();
114 if ( error )
115 *error = KLibLoader::ErrNoComponent;
116 }
117 return res;
118 }
119#endif
120
121 /**
122 * @deprecated use KService::createInstance instead
123 */
124#ifndef KDE_NO_DEPRECATED
125 template <class T>
126 KDE_DEPRECATED T *createPartInstanceFromService( const KService::Ptr &service,
127 QWidget *parentWidget = 0,
128 QObject *parent = 0,
129 const QStringList &args = QStringList(),
130 int *error = 0 )
131 {
132 QString library = service->library();
133 if ( library.isEmpty() )
134 {
135 if ( error )
136 *error = KLibLoader::ErrServiceProvidesNoLibrary;
137 return 0;
138 }
139
140 return createPartInstanceFromLibrary<T>( QFile::encodeName( library ).constData(), parentWidget,
141 parent, args, error );
142 }
143#endif
144
145#ifndef KDE_NO_DEPRECATED
146 template <class T, class ServiceIterator>
147 KDE_DEPRECATED T *createPartInstanceFromServices( ServiceIterator begin,
148 ServiceIterator end,
149 QWidget *parentWidget = 0,
150 QObject *parent = 0,
151 const QStringList &args = QStringList(),
152 int *error = 0 )
153 {
154 for (; begin != end; ++begin )
155 {
156 KService::Ptr service = *begin;
157
158 if ( error )
159 *error = 0;
160
161 T *component = createPartInstanceFromService<T>( service, parentWidget,
162 parent, args, error );
163 if ( component )
164 return component;
165 }
166
167 if ( error )
168 *error = KLibLoader::ErrNoServiceFound;
169
170 return 0;
171
172 }
173#endif
174
175 /**
176 * This method creates and returns a KParts part from a serviceType (e.g. a mimetype).
177 *
178 * You can use this method to create a generic viewer - that can display any
179 * kind of file, provided that there is a ReadOnlyPart installed for it - in 5 lines:
180 * \code
181 * // Given the following: KUrl url, QWidget* parentWidget and QObject* parentObject.
182 * QString mimetype = KMimeType::findByURL( url )->name();
183 * KParts::ReadOnlyPart* part = KParts::ComponentFactory::createPartInstanceFromQuery<KParts::ReadOnlyPart>( mimetype, QString(), parentWidget, parentObject );
184 * if ( part ) {
185 * part->openUrl( url );
186 * part->widget()->show(); // also insert the widget into a layout, or simply use a KVBox as parentWidget
187 * }
188 * \endcode
189 *
190 * @deprecated use KMimeTypeTrader::createPartInstanceFromQuery instead
191 *
192 * @param mimeType the mimetype which this part is associated with
193 * @param constraint an optional constraint to pass to the trader (see KTrader)
194 * @param parentWidget the parent widget, will be set as the parent of the part's widget
195 * @param parent the parent object for the part itself
196 * @param args A list of string arguments, passed to the factory and possibly
197 * to the component (see KLibFactory)
198 * @param error The int passed here will receive an error code in case of errors.
199 * (See enum KLibLoader::ComponentLoadingError)
200 * @return A pointer to the newly created object or a null pointer if the
201 * factory was unable to create an object of the given type.
202 */
203#ifndef KDE_NO_DEPRECATED
204 template <class T>
205 KDE_DEPRECATED T *createPartInstanceFromQuery( const QString &mimeType,
206 const QString &constraint,
207 QWidget *parentWidget = 0,
208 QObject *parent = 0,
209 const QStringList &args = QStringList(),
210 int *error = 0 )
211 {
212 const KService::List offers = KMimeTypeTrader::self()->query( mimeType, QLatin1String("KParts/ReadOnlyPart"), constraint );
213 if ( offers.isEmpty() )
214 {
215 if ( error )
216 *error = KLibLoader::ErrNoServiceFound;
217 return 0;
218 }
219
220 return createPartInstanceFromServices<T>( offers.begin(), offers.end(),
221 parentWidget,
222 parent, args, error );
223 }
224#endif // KDE_NO_DEPRECATED
225 }
226}
227
228/*
229 * vim: et sw=4
230 */
231
232#endif
233