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 | |
36 | class QWebFrame; |
37 | class 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 | */ |
64 | class KDEWEBKIT_EXPORT KWebWallet : public QObject |
65 | { |
66 | Q_OBJECT |
67 | |
68 | public: |
69 | |
70 | /** |
71 | * Holds data from a HTML <form> element. |
72 | */ |
73 | struct WebForm |
74 | { |
75 | /** |
76 | * A typedef for storing the name and value attributes of HTML <input> |
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 | |
180 | public 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 | |
205 | Q_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 | |
247 | protected: |
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 | |
314 | private: |
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 | |