1/*
2 * This file is part of the KDE project.
3 *
4 * Copyright (C) 2008 Dirk Mueller <mueller@kde.org>
5 * Copyright (C) 2008 Urs Wolfer <uwolfer @ kde.org>
6 * Copyright (C) 2008 Michael Howell <mhowell123@gmail.com>
7 * Copyright (C) 2009,2010 Dawit Alemayehu <adawit @ kde.org>
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
18 *
19 * You should have received a copy of the GNU Library General Public License
20 * along with this library; see the file COPYING.LIB. If not, write to
21 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 * Boston, MA 02110-1301, USA.
23 *
24 */
25#ifndef KWEBPAGE_H
26#define KWEBPAGE_H
27
28#include <kdewebkit_export.h>
29
30#include <QtWebKit/QWebPage>
31
32class KWebWallet;
33class KUrl;
34class KJob;
35
36namespace KIO {
37 class MetaData;
38 class Job;
39}
40
41/**
42 * @short An enhanced QWebPage that provides integration into the KDE environment.
43 *
44 * This is a convenience class that provides full integration with KDE
45 * technologies such as KIO for network request handling, KCookiejar for cookie
46 * handling, KParts for embedding non-html content and KWallet for storing
47 * form data. It also sets standard icons for many of the actions provided by
48 * QWebPage.
49 *
50 * Most of this integration happens behind the scenes. If you want KWallet
51 * integration, however, you will have to provide a mechanism for deciding
52 * whether to allow form data to be stored. To do this, you will need to
53 * connect to the KWebWallet::saveFormDataRequested signal and call either
54 * KWebWallet::acceptSaveFormDataRequest or
55 * KWebWallet::rejectSaveFormDataRequest, typically after asking the user
56 * whether they want to save the form data. If you do not do this, no form
57 * data will be saved.
58 *
59 * KWebPage will also not automatically load form data for you. You should
60 * connect to QWebPage::loadFinished and, if the page was loaded successfully,
61 * call
62 * @code
63 * page->wallet()->fillFormData(page->mainFrame());
64 * @endcode
65 *
66 * @see KIO::Integration
67 * @see KWebWallet
68 *
69 * @author Urs Wolfer <uwolfer @ kde.org>
70 * @author Dawit Alemayehu <adawit @ kde.org>
71 *
72 * @since 4.4
73 */
74
75class KDEWEBKIT_EXPORT KWebPage : public QWebPage
76{
77 Q_OBJECT
78 Q_FLAGS (Integration)
79
80public:
81 /**
82 * Flags for setting the desired level of integration.
83 */
84 enum IntegrationFlags
85 {
86 /**
87 * Provide only very basic integration such as using KDE icons for the
88 * actions provided by QWebPage.
89 */
90 NoIntegration = 0x01,
91 /**
92 * Use KIO to handle network requests.
93 *
94 * @see KIO::Integration::AccessManager
95 */
96 KIOIntegration = 0x02,
97 /**
98 * Use KPart componenets, if available, to display content in
99 * &lt;embed&gt; and &lt;object&gt; tags.
100 */
101 KPartsIntegration = 0x04,
102 /**
103 * Use KWallet to store login credentials and other form data from web
104 * sites.
105 *
106 * @see wallet() and setWallet()
107 */
108 KWalletIntegration = 0x08
109 };
110 Q_DECLARE_FLAGS(Integration, IntegrationFlags)
111
112 /**
113 * Constructs a KWebPage with parent @p parent.
114 *
115 * Note that if no integration flags are set (the default), all integration
116 * options are activated. If you inherit from this class you can use the
117 * flags in @ref IntegrationFlags to control how much integration should
118 * be used.
119 *
120 * @see KIO::Integration::CookieJar
121 * @see KIO::Integration::AccessManager
122 * @see wallet() and setWallet()
123 */
124 explicit KWebPage(QObject *parent = 0, Integration flags = Integration());
125
126 /**
127 * Destroys the KWebPage.
128 */
129 ~KWebPage();
130
131 /**
132 * Whether access to remote content is permitted.
133 *
134 * If this is @c false, only resources on the local system can be accessed
135 * through this web page. By default access to remote content is allowed.
136 *
137 * If KIO integration is disabled, this will always return @c true.
138 *
139 * @see setAllowExternalContent()
140 * @see KIO::Integration::AccessManager::isExternalContentAllowed()
141 *
142 * @return @c true if access to remote content is permitted, @c false otherwise
143 */
144 bool isExternalContentAllowed() const;
145
146 /**
147 * The wallet integration manager.
148 *
149 * If you wish to use KDE wallet integration, you will have to connect to
150 * signals emitted by this object and react accordingly. See KWebWallet
151 * for more information.
152 *
153 * @return the wallet integration manager, or 0 if KDE wallet integration
154 * is disabled
155 */
156 KWebWallet *wallet() const;
157
158 /**
159 * Set whether to allow remote content.
160 *
161 * If KIO integration is not enabled, this method will have no effect.
162 *
163 * @see isExternalContentAllowed()
164 * @see KIO::Integration::AccessManager::setAllowExternalContent(bool)
165 *
166 * @param allow @c true if access to remote content should be allowed,
167 * @c false if only local content should be accessible
168 */
169 void setAllowExternalContent(bool allow);
170
171 /**
172 * Set the @ref KWebWallet that is used to store form data.
173 *
174 * This KWebPage will take ownership of @p wallet, so that the wallet
175 * is deleted when the KWebPage is deleted. If you do not want that
176 * to happen, you should call setParent() on @p wallet after calling
177 * this function.
178 *
179 * @see KWebWallet
180 *
181 * @param wallet the KWebWallet to be used for storing form data, or
182 * 0 to disable KWallet integration
183 */
184 void setWallet(KWebWallet* wallet);
185
186public Q_SLOTS:
187 /**
188 * Download @p request using KIO.
189 *
190 * This slot first prompts the user where to save the requested
191 * resource and then downloads it using KIO.
192 */
193 virtual void downloadRequest(const QNetworkRequest &request);
194
195 /**
196 * Download @p url using KIO.
197 *
198 * This slot first prompts the user where to save the requested
199 * resource and then downloads it using KIO.
200 */
201 virtual void downloadUrl(const KUrl &url);
202
203 /**
204 * Download the resource specified by @p reply using KIO.
205 *
206 * This slot first prompts the user where to save the requested resource
207 * and then downloads it using KIO.
208 *
209 * In KDE 4.8 and higher, if @p reply contains a QObject property called
210 * "DownloadManagerExe", then an attempt will be made to the command
211 * specified by that property to download the specified resource.
212 *
213 * If the "DownloadManagerExe" property is not defined or the command
214 * specified by it could not be successfully executed, then the user will
215 * be prompted for the action to take.
216 *
217 * @since 4.5
218 * @see handleReply
219 */
220 void downloadResponse(QNetworkReply *reply);
221
222protected:
223 /**
224 * Get an item of session metadata.
225 *
226 * Retrieves the value of the permanent (per-session) metadata for @p key.
227 *
228 * If KIO integration is disabled, this will always return an empty string.
229 *
230 * @see KIO::Integration::AccessManager::sessionMetaData
231 * @see setSessionMetaData
232 *
233 * @param key the key of the metadata to retrieve
234 * @return the value of the metadata associated with @p key, or an
235 * empty string if there is no such metadata
236 */
237 QString sessionMetaData(const QString &key) const;
238
239 /**
240 * Get an item of request metadata.
241 *
242 * Retrieves the value of the temporary (per-request) metadata for @p key.
243 *
244 * If KIO integration is disabled, this will always return an empty string.
245 *
246 * @see KIO::Integration::AccessManager::requestMetaData
247 * @see setRequestMetaData
248 *
249 * @param key the key of the metadata to retrieve
250 * @return the value of the metadata associated with @p key, or an
251 * empty string if there is no such metadata
252 */
253 QString requestMetaData(const QString &key) const;
254
255 /**
256 * Set an item of metadata to be sent to the KIO slave with every request.
257 *
258 * If KIO integration is disabled, this method will have no effect.
259 *
260 * Metadata set using this method will be sent with every request.
261 *
262 * @see KIO::Integration::AccessManager::sessionMetaData
263 *
264 * @param key the key for the metadata; any existing metadata associated
265 * with this key will be overwritten
266 * @param value the value to associate with @p key
267 */
268 void setSessionMetaData(const QString &key, const QString &value);
269
270 /**
271 * Set an item of metadata to be sent to the KIO slave with the next request.
272 *
273 * If KIO integration is disabled, this method will have no effect.
274 *
275 * Metadata set using this method will be deleted after it has been sent
276 * once.
277 *
278 * @see KIO::Integration::AccessManager::requestMetaData
279 *
280 * @param key the key for the metadata; any existing metadata associated
281 * with this key will be overwritten
282 * @param value the value to associate with @p key
283 */
284 void setRequestMetaData(const QString &key, const QString &value);
285
286 /**
287 * Remove an item of session metadata.
288 *
289 * Removes the permanent (per-session) metadata associated with @p key.
290 *
291 * @see KIO::Integration::AccessManager::sessionMetaData
292 * @see setSessionMetaData
293 *
294 * @param key the key for the metadata to remove
295 */
296 void removeSessionMetaData(const QString &key);
297
298 /**
299 * Remove an item of request metadata.
300 *
301 * Removes the temporary (per-request) metadata associated with @p key.
302 *
303 * @see KIO::Integration::AccessManager::requestMetaData
304 * @see setRequestMetaData
305 *
306 * @param key the key for the metadata to remove
307 */
308 void removeRequestMetaData(const QString &key);
309
310 /**
311 * @reimp
312 *
313 * This function is re-implemented to provide KDE user-agent management
314 * integration through KProtocolManager.
315 *
316 * If a special user-agent has been configured for the host indicated by
317 * @p url, that user-agent will be returned. Otherwise, QWebPage's
318 * default user agent is returned.
319 *
320 * @see KProtocolManager::userAgentForHost.
321 * @see QWebPage::userAgentForUrl.
322 */
323 virtual QString userAgentForUrl(const QUrl& url) const;
324
325 /**
326 * @reimp
327 *
328 * This performs various integration-related actions when navigation is
329 * requested. If you override this method, make sure you call the parent's
330 * implementation unless you want to block the request outright.
331 *
332 * If you do override acceptNavigationRequest and call this method,
333 * however, be aware of the effect of the page's linkDelegationPolicy on
334 * how * QWebPage::acceptNavigationRequest behaves.
335 *
336 * @see QWebPage::acceptNavigationRequest
337 */
338 virtual bool acceptNavigationRequest(QWebFrame * frame, const QNetworkRequest & request, NavigationType type);
339
340 /**
341 * Attempts to handle @p reply and returns true on success, false otherwise.
342 *
343 * In KDE 4.8 and higher, if @p reply contains a QObject property called
344 * "DownloadManagerExe", then an attempt will be made to let the command
345 * specified by that property to download the requested resource.
346 *
347 * If the "DownloadManagerExe" property is not defined or the command
348 * specified by it could not be successfully executed, then the user will
349 * be prompted for the action to take.
350 *
351 * @param reply the QNetworkReply object to be handled.
352 * @param contentType if not null, it will be set to the content-type specified in @p reply, if any.
353 * @param metaData if not null, it will be set to the KIO meta-data specified in @p reply, if any.
354 * @since 4.6.3
355 */
356 bool handleReply (QNetworkReply* reply, QString* contentType = 0, KIO::MetaData* metaData = 0);
357
358private:
359 class KWebPagePrivate;
360 KWebPagePrivate* const d;
361 Q_PRIVATE_SLOT(d, void _k_copyResultToTempFile(KJob*))
362 Q_PRIVATE_SLOT(d, void _k_receivedContentType(KIO::Job*, const QString&))
363 Q_PRIVATE_SLOT(d, void _k_contentTypeCheckFailed(KJob*))
364};
365
366Q_DECLARE_OPERATORS_FOR_FLAGS(KWebPage::Integration)
367
368#endif // KWEBPAGE_H
369