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 | |
32 | class KWebWallet; |
33 | class KUrl; |
34 | class KJob; |
35 | |
36 | namespace 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 | |
75 | class KDEWEBKIT_EXPORT KWebPage : public QWebPage |
76 | { |
77 | Q_OBJECT |
78 | Q_FLAGS (Integration) |
79 | |
80 | public: |
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 | * <embed> and <object> 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 | |
186 | public 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 | |
222 | protected: |
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 | |
358 | private: |
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 | |
366 | Q_DECLARE_OPERATORS_FOR_FLAGS(KWebPage::Integration) |
367 | |
368 | #endif // KWEBPAGE_H |
369 | |