1/*
2    Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies)
3
4    This library is free software; you can redistribute it and/or
5    modify it under the terms of the GNU Library General Public
6    License as published by the Free Software Foundation; either
7    version 2 of the License, or (at your option) any later version.
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#include "config.h"
21#include "qwebpluginfactory.h"
22
23/*!
24    \class QWebPluginFactory
25    \since 4.4
26    \brief The QWebPluginFactory class is used to embed custom data types in web pages.
27
28    \inmodule QtWebKit
29
30    The HTML \c{<object>} tag is used to embed arbitrary content into a web page,
31    for example:
32
33    \code
34    <object type="application/x-pdf" data="http://qt.nokia.com/document.pdf" width="500" height="400"></object>
35    \endcode
36
37    QtWebkit will natively handle the most basic data types like \c{text/html} and
38    \c{image/jpeg}, but for any advanced or custom data types you will need to
39    provide a handler yourself.
40
41    QWebPluginFactory is a factory for creating plugins for QWebPage, where each
42    plugin provides support for one or more data types. A plugin factory can be
43    installed on a QWebPage using QWebPage::setPluginFactory().
44
45    \note The plugin factory is only used if plugins are enabled through QWebSettings.
46
47    You provide a QWebPluginFactory by implementing the plugins() and the
48    create() methods. For plugins() it is necessary to describe the plugins the
49    factory can create, including a description and the supported MIME types.
50    The MIME types each plugin can handle should match the ones specified in
51    in the HTML \c{<object>} tag of your content.
52
53    The create() method is called if the requested MIME type is supported. The
54    implementation has to return a new instance of the plugin requested for the
55    given MIME type and the specified URL.
56
57    The plugins themselves are subclasses of QObject, but currently only plugins
58    based on either QWidget or QGraphicsWidget are supported.
59
60*/
61
62
63/*!
64    \class QWebPluginFactory::Plugin
65    \since 4.4
66    \brief The QWebPluginFactory::Plugin structure describes the properties of a plugin a QWebPluginFactory can create.
67
68    \inmodule QtWebKit
69*/
70
71/*!
72    \variable QWebPluginFactory::Plugin::name
73    The name of the plugin.
74*/
75
76/*!
77    \variable QWebPluginFactory::Plugin::description
78    The description of the plugin.
79*/
80
81/*!
82    \variable QWebPluginFactory::Plugin::mimeTypes
83    The list of mime types supported by the plugin.
84*/
85
86/*!
87    \class QWebPluginFactory::MimeType
88    \since 4.4
89    \brief The QWebPluginFactory::MimeType structure describes a mime type supported by a plugin.
90
91    \inmodule QtWebKit
92*/
93
94/*!
95    Returns true if this mimetype is the same as the \a other mime type.
96*/
97bool QWebPluginFactory::MimeType::operator==(const MimeType& other) const
98{
99    return name == other.name
100           && description == other.description
101           && fileExtensions == other.fileExtensions;
102}
103
104/*!
105    \fn bool QWebPluginFactory::MimeType::operator!=(const MimeType& other) const
106
107    Returns true if this mimetype is different from the \a other mime type.
108*/
109
110/*!
111    \variable QWebPluginFactory::MimeType::name
112
113    The full name of the MIME type; e.g., \c{text/plain} or \c{image/png}.
114*/
115
116/*!
117    \variable QWebPluginFactory::MimeType::description
118    The description of the mime type.
119*/
120
121/*!
122    \variable QWebPluginFactory::MimeType::fileExtensions
123    The list of file extensions that are used by this mime type.
124
125    For example, a mime type for PDF documents would return "pdf" as its file extension.
126*/
127
128/*!
129    Constructs a QWebPluginFactory with parent \a parent.
130*/
131QWebPluginFactory::QWebPluginFactory(QObject *parent)
132    : QObject(parent)
133{
134}
135
136/*!
137    Destructor.
138*/
139QWebPluginFactory::~QWebPluginFactory()
140{
141}
142
143/*!
144    \fn QList<Plugin> QWebPluginFactory::plugins() const = 0
145
146    This function is reimplemented in subclasses to return a list of
147    supported plugins the factory can create.
148
149    \note Currently, this function is only called when JavaScript programs
150    access the global \c plugins or \c mimetypes objects.
151*/
152
153/*!
154    This function is called to refresh the list of supported plugins. It may be called after a new plugin
155    has been installed in the system.
156*/
157void QWebPluginFactory::refreshPlugins()
158{
159}
160
161/*!
162    \fn QObject *QWebPluginFactory::create(const QString &mimeType, const QUrl &url,
163    const QStringList &argumentNames, const QStringList &argumentValues) const = 0
164
165    Implemented in subclasses to create a new plugin that can display content of
166    the MIME type given by \a mimeType. The URL of the content is provided in \a url.
167    The returned object should be a QWidget.
168
169    The HTML object element can provide parameters through the \c{<param>} tag.
170    The name and the value attributes of these tags are specified by the
171    \a argumentNames and \a argumentValues string lists.
172
173    For example:
174
175    \code
176    <object type="application/x-pdf" data="http://qt.nokia.com/document.pdf" width="500" height="400">
177        <param name="showTableOfContents" value="true" />
178        <param name="hideThumbnails" value="false" />
179    </object>
180    \endcode
181
182    The above object element will result in a call to create() with the following arguments:
183    \table
184    \header \o Parameter
185            \o Value
186    \row    \o mimeType
187            \o "application/x-pdf"
188    \row    \o url
189            \o "http://qt.nokia.com/document.pdf"
190    \row    \o argumentNames
191            \o "showTableOfContents" "hideThumbnails"
192    \row    \o argumentVaues
193            \o "true" "false"
194    \endtable
195
196    \note Ownership of the returned object will be transferred to the caller.
197*/
198
199/*!
200    \enum QWebPluginFactory::Extension
201    \internal
202
203    This enum describes the types of extensions that the plugin factory can support. Before using these extensions, you
204    should verify that the extension is supported by calling supportsExtension().
205
206    Currently there are no extensions.
207*/
208
209/*!
210    \class QWebPluginFactory::ExtensionOption
211    \internal
212    \since 4.4
213    \brief The ExtensionOption class provides an extended input argument to QWebPluginFactory's extension support.
214
215    \inmodule QtWebKit
216
217    \sa QWebPluginFactory::extension()
218*/
219
220/*!
221    \class QWebPluginFactory::ExtensionReturn
222    \internal
223    \since 4.4
224    \brief The ExtensionOption class provides an extended output argument to QWebPluginFactory's extension support.
225
226    \inmodule QtWebKit
227
228    \sa QWebPluginFactory::extension()
229*/
230
231/*!
232    This virtual function can be reimplemented in a QWebPluginFactory subclass to provide support for extensions. The \a option
233    argument is provided as input to the extension; the output results can be stored in \a output.
234
235    \internal
236
237    The behaviour of this function is determined by \a extension.
238
239    You can call supportsExtension() to check if an extension is supported by the factory.
240
241    By default, no extensions are supported, and this function returns false.
242
243    \sa supportsExtension(), Extension
244*/
245bool QWebPluginFactory::extension(Extension extension, const ExtensionOption *option, ExtensionReturn *output)
246{
247    Q_UNUSED(extension)
248    Q_UNUSED(option)
249    Q_UNUSED(output)
250    return false;
251}
252
253/*!
254    This virtual function returns true if the plugin factory supports \a extension; otherwise false is returned.
255
256    \internal
257
258    \sa extension()
259*/
260bool QWebPluginFactory::supportsExtension(Extension extension) const
261{
262    Q_UNUSED(extension)
263    return false;
264}
265