1/* This file is part of the KDE project
2 Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
3 (C) 1999 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 GNU
13 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
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20#ifndef __kparts_factory_h__
21#define __kparts_factory_h__
22
23#include <klibloader.h>
24
25#include <kparts/kparts_export.h>
26
27class QWidget;
28
29namespace KParts
30{
31
32class Part;
33
34/**
35 * A generic factory object to create a Part.
36 *
37 * Factory is an abstract class. Reimplement the
38 * createPartObject() method to give it functionality.
39 *
40 * @see KLibFactory.
41 */
42class KPARTS_EXPORT Factory : public KLibFactory
43{
44 Q_OBJECT
45public:
46 Factory( QObject *parent = 0 );
47 virtual ~Factory();
48
49 /**
50 * Creates a part.
51 *
52 * The QStringList can be used to pass additional arguments to the part.
53 * If the part needs additional arguments, it should take them as
54 * name="value" pairs. This is the way additional arguments will get passed
55 * to the part from eg. khtml. You can for example emebed the part into HTML
56 * by using the following code:
57 * \code
58 * <object type="my_mimetype" data="url_to_my_data">
59 * <param name="name1" value="value1">
60 * <param name="name2" value="value2">
61 * </object>
62 * \endcode
63 * This could result in a call to
64 * \code
65 * createPart( parentWidget, parentObject, "KParts::Part",
66 * QStringList("name1="value1"", "name2="value2") );
67 * \endcode
68 *
69 * @returns the newly created part.
70 *
71 * createPart() automatically emits a signal KLibFactory::objectCreated to tell
72 * the library about its newly created object. This is very
73 * important for reference counting, and allows unloading the
74 * library automatically once all its objects have been destroyed.
75 */
76 Part *createPart( QWidget *parentWidget = 0, QObject *parent = 0, const char *classname = "KParts::Part", const QStringList &args = QStringList() );
77
78 /**
79 * If you have a part contained in a shared library you might want to query
80 * for meta-information like the about-data, or the KComponentData in general.
81 * If the part is exported using KParts::GenericFactory then this method will
82 * return the instance that belongs to the part without the need to instantiate
83 * the part component.
84 */
85 virtual KComponentData partComponentData();
86
87 /**
88 * A convenience method for partComponentData that takes care of retrieving
89 * the factory for a given library name and calling partComponentData on it.
90 *
91 * @param libraryName name of the library to query the instance from
92 */
93 static KComponentData partComponentDataFromLibrary(const QString &libraryName);
94
95protected:
96
97 /**
98 * Reimplement this method in your implementation to create the Part.
99 *
100 * The QStringList can be used to pass additional arguments to the part.
101 * If the part needs additional arguments, it should take them as
102 * name="value" pairs. This is the way additional arguments will get passed
103 * to the part from eg. khtml. You can for example emebed the part into HTML
104 * by using the following code:
105 * \code
106 * <object type="my_mimetype" data="url_to_my_data">
107 * <param name="name1" value="value1">
108 * <param name="name2" value="value2">
109 * </object>
110 * \endcode
111 * This could result in a call to
112 * \code
113 * createPart( parentWidget, parentObject, "KParts::Part",
114 * QStringList("name1="value1"", "name2="value2") );
115 * \endcode
116 *
117 * @returns the newly created part.
118 */
119 virtual Part *createPartObject( QWidget *parentWidget = 0, QObject *parent = 0, const char *classname = "KParts::Part", const QStringList &args = QStringList() ) = 0;
120
121 /**
122 * Reimplemented from KLibFactory. Calls createPart()
123 */
124 virtual QObject *createObject( QObject *parent = 0, const char *classname = "QObject", const QStringList &args = QStringList() );
125
126};
127
128}
129
130/*
131 * vim: et sw=4
132 */
133
134#endif
135