1/*
2 * This file is part of the KDE project.
3 *
4 * Copyright (C) 2009 Dawit Alemayehu <adawit@kde.org>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 *
21 */
22#ifndef KWEBWALLET_H
23#define KWEBWALLET_H
24
25#include <kdewebkit_export.h>
26
27#include <kurl.h>
28
29#include <QtCore/QObject>
30#include <QtCore/QString>
31#include <QtCore/QList>
32#include <QtCore/QPair>
33#include <QtGui/QWidget>
34#include <QtCore/QtGlobal>
35
36class QWebFrame;
37class QWebPage;
38
39
40/**
41 * @short A class that provides KDE wallet integration for QWebFrame.
42 *
43 * Normally, you will use this class via KWebPage. In this case, you need to
44 * connect to the saveFormDataRequested signal and call either
45 * acceptSaveFormDataRequest or rejectSaveFormDataRequest, typically after
46 * asking the user whether they want to save the form data.
47 *
48 * You will also need to call fillFormData when a QWebFrame has finished
49 * loading. To do this, connect to QWebPage::loadFinished and, if the page was
50 * loaded successfully, call
51 * @code
52 * page->wallet()->fillFormData(page->mainFrame());
53 * @endcode
54 *
55 * If you wish to use this directly with a subclass of QWebPage, you should call
56 * saveFormData from QWebPage::acceptNavigationRequest when a user submits a
57 * form.
58 *
59 * @see KWebPage
60 *
61 * @author Dawit Alemayehu <adawit @ kde.org>
62 * @since 4.4
63 */
64class KDEWEBKIT_EXPORT KWebWallet : public QObject
65{
66 Q_OBJECT
67
68public:
69
70 /**
71 * Holds data from a HTML &lt;form&gt; element.
72 */
73 struct WebForm
74 {
75 /**
76 * A typedef for storing the name and value attributes of HTML &lt;input&gt;
77 * elements.
78 */
79 typedef QPair<QString, QString> WebField;
80
81 /** The URL the form was found at. */
82 QUrl url;
83 /** The name attribute of the form. */
84 QString name;
85 /** The position of the form on the web page, relative to other forms. */
86 QString index;
87 /** The name and value attributes of each input element in the form. */
88 QList<WebField> fields;
89 };
90
91 /**
92 * A list of web forms
93 */
94 typedef QList<WebForm> WebFormList;
95
96 /**
97 * Constructs a KWebWallet
98 *
99 * @p parent is usually the QWebPage this wallet is being used for.
100 *
101 * The @p wid parameter is used to tell KDE's wallet manager which window
102 * is requesting access to the wallet.
103 *
104 * @param parent the owner of this wallet
105 * @param wid the window ID of the window the web page will be
106 * embedded in
107 */
108 explicit KWebWallet(QObject* parent = 0, WId wid = 0);
109
110 /**
111 * Destructor
112 */
113 virtual ~KWebWallet();
114
115 /**
116 * Returns a list of forms in @p frame that have cached data in the
117 * peristent storage.
118 *
119 * If @p recursive is set to true, the default, then this function will
120 * will also return the cached form data for all the children frames of
121 * @p frame.
122 *
123 * If the site currently rendered in @p frame does not contain any forms
124 * or there is no cached data for the forms found in @p frame, then this
125 * function will return an empty list.
126 *
127 * Note that this function will only return the information about the forms
128 * in @p frame and not their cached data, i.e. the fields member variable in
129 * the returned @ref WebForm list will always be empty.
130 */
131 WebFormList formsWithCachedData(QWebFrame* frame, bool recursive = true) const;
132
133 /**
134 * Attempts to save the form data from @p frame and its children frames.
135 *
136 * If @p recursive is set to true, the default, then form data from all
137 * the child frames of @p frame will be saved. Set @p ignorePasswordFields
138 * to true if you do not want data from password fields to not be saved.
139 *
140 * You must connect to the @ref saveFormDataRequested signal and call either
141 * @ref rejectSaveFormDataRequest or @ref acceptSaveFormDataRequest signals
142 * in order to complete the save request. Otherwise, you request will simply
143 * be ignored.
144 */
145 void saveFormData(QWebFrame *frame, bool recursive = true, bool ignorePasswordFields = false);
146
147 /**
148 * Attempts to fill forms contained in @p frame with cached data.
149 *
150 * If @p recursive is set to true, the default, then this function will
151 * attempt to fill out forms in the specified frame and all its children
152 * frames.
153 */
154 void fillFormData(QWebFrame *frame, bool recursive = true);
155
156 /**
157 * Removes the form data specified by @p forms from the persistent storage.
158 *
159 * This function is provided for convenience and simply calls @ref formsWithCachedData
160 * and @ref removeFormData(WebFormList). Note that this function will remove all cached
161 * data for forms found in @p frame. If @p recursive is set to true, then
162 * all cached data for all of the child frames of @p frame will be removed
163 * from the persistent storage as well.
164 *
165 * @see formsWithCachedData
166 * @see removeFormData
167 */
168 void removeFormData (QWebFrame *frame, bool recursive);
169
170 /**
171 * Removes the form data specified by @p forms from the persistent storage.
172 *
173 * Call @ref formsWithCachedData to obtain a list of forms with data cached
174 * in persistent storage.
175 *
176 * @see formsWithCachedData
177 */
178 void removeFormData(const WebFormList &forms);
179
180public Q_SLOTS:
181 /**
182 * Accepts the save form data request associated with @p key.
183 *
184 * The @p key parameter is the one sent through the @ref saveFormDataRequested
185 * signal.
186 *
187 * You must always call this function or @ref rejectSaveFormDataRequest in
188 * order to complete the save form data request. Otherwise, the request will
189 * simply be ignored.
190 *
191 * @see saveFormDataRequested.
192 */
193 void acceptSaveFormDataRequest(const QString &key);
194
195 /**
196 * Rejects the save form data request associated with @p key.
197 *
198 * The @p key parameter is the one sent through the @ref saveFormDataRequested
199 * signal.
200 *
201 * @see saveFormDataRequested.
202 */
203 void rejectSaveFormDataRequest(const QString &key);
204
205Q_SIGNALS:
206 /**
207 * This signal is emitted whenever a save form data request is received.
208 *
209 * Unless you connect to this signal and and call @ref acceptSaveFormDataRequest
210 * or @ref rejectSaveFormDataRequest slots, the save form data requested through
211 * @ref saveFormData will simply be ignored.
212 *
213 * @p key is a value that uniquely identifies the save request and @p url
214 * is the address for which the form data is being saved.
215 *
216 * @see acceptSaveFormDataRequest
217 * @see rejectSaveFormDataRequest
218 */
219 void saveFormDataRequested(const QString &key, const QUrl &url);
220
221 /**
222 * This signal is emitted whenever a save form data request is completed.
223 *
224 * @p ok will be set to true if the save form data request for @p url was
225 * completed successfully.
226 *
227 * @see saveFormDataRequested
228 */
229 void saveFormDataCompleted(const QUrl &url, bool ok);
230
231 /**
232 * This signal is emitted whenever a fill form data request is completed.
233 *
234 * @p ok will be set to true if any forms were successfully filled with
235 * cached data from the persistent storage.
236 *
237 * @see fillFormData
238 * @since 4.5
239 */
240 void fillFormRequestCompleted(bool ok);
241
242 /**
243 * This signal is emitted whenever the current wallet is closed.
244 */
245 void walletClosed();
246
247protected:
248 /**
249 * Returns a list of forms for @p url that are waiting to be filled.
250 *
251 * This function returns an empty list if there is no pending requests
252 * for filling forms associated with @p url.
253 */
254 WebFormList formsToFill(const KUrl &url) const;
255
256 /**
257 * Returns a list of for @p key that are waiting to be saved.
258 *
259 * This function returns an empty list if there are no pending requests
260 * for saving forms associated with @p key.
261 */
262 WebFormList formsToSave(const QString &key) const;
263
264 /**
265 * Returns forms to be removed from persistent storage.
266 */
267 WebFormList formsToDelete() const;
268
269 /**
270 * Returns true when there is data associated with @p form in the
271 * persistent storage.
272 */
273 virtual bool hasCachedFormData(const WebForm &form) const;
274
275 /**
276 * Fills the web forms in frame that point to @p url with data from @p forms.
277 *
278 * @see fillFormDataFromCache.
279 */
280 void fillWebForm(const KUrl &url, const WebFormList &forms);
281
282 /**
283 * Fills form data from persistent storage.
284 *
285 * If you reimplement this function, call @ref formsToFill to obtain
286 * the list of forms pending to be filled. Once you fill the list with
287 * the cached data from the persistent storage, you must call @p fillWebForm
288 * to fill out the actual web forms.
289 *
290 * @see formsToFill
291 */
292 virtual void fillFormDataFromCache(const KUrl::List &list);
293
294 /**
295 * Stores form data associated with @p key to a persistent storage.
296 *
297 * If you reimplement this function, call @ref formsToSave to obtain the
298 * list of form data pending to be saved to persistent storage.
299 *
300 *@see formsToSave
301 */
302 virtual void saveFormDataToCache(const QString &key);
303
304 /**
305 * Removes all cached form data associated with @p forms from persistent storage.
306 *
307 * If you reimplement this function, call @ref formsToDelete to obtain the
308 * list of form data pending to be removed from persistent storage.
309 *
310 *@see formsToDelete
311 */
312 virtual void removeFormDataFromCache(const WebFormList &forms);
313
314private:
315 class KWebWalletPrivate;
316 friend class KWebWalletPrivate;
317 KWebWalletPrivate * const d;
318
319 Q_PRIVATE_SLOT(d, void _k_openWalletDone(bool))
320 Q_PRIVATE_SLOT(d, void _k_walletClosed())
321};
322
323#endif // KWEBWALLET_H
324