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