1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 2000 David Faure <faure@kde.org> |
3 | Copyright (C) 2000 Dawit Alemayehu <adawit@kde.org> |
4 | Copyright (C) 2007 Olivier Goffart <ogoffart at 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 version 2 as published by the Free Software Foundation. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Library General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public |
16 | License along with this library; see the file COPYING.LIB. If |
17 | not, write to the Free Software Foundation, Inc., 51 Franklin Street, |
18 | Fifth Floor, Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef KPASSWORDDIALOG_H |
22 | #define KPASSWORDDIALOG_H |
23 | |
24 | #include <kdialog.h> |
25 | #include <QtCore/QFlags> |
26 | |
27 | /** |
28 | * A dialog for requesting a password and optionaly a login from the end user. |
29 | * |
30 | * \section usage Usage Example |
31 | * |
32 | * Requesting a simple password, assynchronous |
33 | * |
34 | * \code |
35 | * KPasswordDialog *dlg = new KPasswordDialog( parent ); |
36 | * dlg->setPrompt(i18n("Enter a password")); |
37 | * connect( dlg, SIGNAL( gotPassword( const QString& , bool ) ) , this, SLOT( setPassword( const QString &) ) ); |
38 | * connect( dlg, SIGNAL( rejected() ) , this, SLOT( slotCancel() ) ); |
39 | * dlg->show(); |
40 | * \endcode |
41 | * |
42 | * Requesting a login and a password, synchronous |
43 | * |
44 | * \code |
45 | * KPasswordDialog dlg(parent, KPasswordDialog::ShowUsernameLine); |
46 | * dlg.setPrompt(i18n("Enter a login and a password")); |
47 | * if( !dlg.exec() ) |
48 | * return; //the user canceled |
49 | * use( dlg.username() , dlg.password() ); |
50 | * \endcode |
51 | * |
52 | * \image html kpassworddialog.png "KDE Password Dialog" |
53 | * |
54 | * @short dialog for requesting login and password from the end user |
55 | */ |
56 | class KDEUI_EXPORT KPasswordDialog : public KDialog |
57 | { |
58 | Q_OBJECT |
59 | |
60 | public: |
61 | |
62 | enum KPasswordDialogFlag |
63 | { |
64 | NoFlags = 0x00, |
65 | /** |
66 | * If this flag is set, the "keep this password" checkbox will been shown, |
67 | * otherwise, it will not be shown and keepPassword will have no effect |
68 | */ |
69 | ShowKeepPassword = 0x01, |
70 | /** |
71 | * If this flag is set, there will be an additional line to let the user enter his login. |
72 | * otherwise, only the password line will be shown. |
73 | */ |
74 | ShowUsernameLine = 0x02, |
75 | /** |
76 | * If this flag is set, the login lineedit will be in read only mode. |
77 | */ |
78 | UsernameReadOnly = 0x04, |
79 | /** |
80 | * If this flag is set, the Anonymous Login checkbox will be displayed |
81 | * @since 4.1 |
82 | */ |
83 | ShowAnonymousLoginCheckBox = 0x08, |
84 | /** |
85 | * If this flag is set, there will be an additional line to let the user enter the domain. |
86 | * @since 4.1 |
87 | */ |
88 | ShowDomainLine = 0x10, |
89 | /** |
90 | * If this flag is set, the domain lineedit will be in read only mode. |
91 | * @since 4.1 |
92 | */ |
93 | DomainReadOnly = 0x20 |
94 | }; |
95 | Q_DECLARE_FLAGS(KPasswordDialogFlags, KPasswordDialogFlag) |
96 | |
97 | enum ErrorType |
98 | { |
99 | UnknownError = 0, |
100 | |
101 | /** |
102 | * A problem with the user name as entered |
103 | **/ |
104 | UsernameError, |
105 | |
106 | /** |
107 | * Incorrect password |
108 | */ |
109 | PasswordError, |
110 | |
111 | /** |
112 | * Error preventing further attempts, will result in disabling most of the interface |
113 | */ |
114 | FatalError, |
115 | |
116 | /** |
117 | * A problem with the domain as entered |
118 | * @since 4.1 |
119 | **/ |
120 | DomainError |
121 | }; |
122 | |
123 | /** |
124 | * create a password dialog |
125 | * |
126 | * @param parent the parent widget (default:NULL). |
127 | * @param flags a set of KPasswordDialogFlag flags |
128 | * @param otherButtons buttons to show in the dialog besides Ok and Cancel. |
129 | * Useful for adding application-specific buttons like |
130 | * "ignore" or "skip". |
131 | */ |
132 | explicit KPasswordDialog( QWidget *parent = 0L, |
133 | const KPasswordDialogFlags& flags = 0, |
134 | const KDialog::ButtonCodes otherButtons = 0); |
135 | |
136 | /** |
137 | * Destructor |
138 | */ |
139 | ~KPasswordDialog(); |
140 | |
141 | /** |
142 | * Sets the prompt to show to the user. |
143 | * @param prompt instructional text to be shown. |
144 | */ |
145 | void setPrompt( const QString& prompt ); |
146 | |
147 | /** |
148 | * Returns the prompt |
149 | */ |
150 | QString prompt() const; |
151 | |
152 | /** |
153 | * set an image that appears next to the prompt. |
154 | */ |
155 | void setPixmap(const QPixmap&); |
156 | /** |
157 | * |
158 | */ |
159 | QPixmap pixmap() const; |
160 | |
161 | /** |
162 | * Adds a comment line to the dialog. |
163 | * |
164 | * This function allows you to add one additional comment |
165 | * line to this widget. Calling this function after a |
166 | * comment has already been added will not have any effect. |
167 | * |
168 | * @param label label for comment (ex:"Command:") |
169 | * @param comment the actual comment text. |
170 | */ |
171 | void ( const QString& label, const QString& ); |
172 | |
173 | /** |
174 | * Shows an error message in the dialog box. Prevents having to show a dialog-on-a-dialog. |
175 | * |
176 | * @param message the error message to show |
177 | */ |
178 | void showErrorMessage( const QString& message, const ErrorType type = PasswordError ); |
179 | |
180 | /** |
181 | * Returns the password entered by the user. |
182 | * @return the password |
183 | */ |
184 | QString password() const; |
185 | |
186 | /** |
187 | * set the default username. |
188 | */ |
189 | void setUsername(const QString&); |
190 | |
191 | /** |
192 | * Returns the username entered by the user. |
193 | * @return the user name |
194 | */ |
195 | QString username() const; |
196 | |
197 | /** |
198 | * set the default domain. |
199 | * @since 4.1 |
200 | */ |
201 | void setDomain(const QString&); |
202 | |
203 | /** |
204 | * Returns the domain entered by the user. |
205 | * @return the domain name |
206 | * @since 4.1 |
207 | */ |
208 | QString domain() const; |
209 | |
210 | /** |
211 | * set anonymous mode (all other fields will be grayed out) |
212 | * @since 4.1 |
213 | */ |
214 | void setAnonymousMode(bool anonymous); |
215 | |
216 | /** |
217 | * @return anonymous mode has been selected. |
218 | * @since 4.1 |
219 | */ |
220 | bool anonymousMode() const; |
221 | |
222 | /** |
223 | * Determines whether supplied authorization should |
224 | * persist even after the application has been closed. |
225 | * |
226 | * this is set with the check password checkbox is the ShowKeepCheckBox flag |
227 | * is set in the constructor, if it is not set, this function return false |
228 | * |
229 | * @return true to keep the password |
230 | */ |
231 | bool keepPassword() const; |
232 | |
233 | /** |
234 | * Check or uncheck the "keep password" checkbox. |
235 | * This can be used to check it before showing the dialog, to tell |
236 | * the user that the password is stored already (e.g. in the wallet). |
237 | * enableKeep must have been set to true in the constructor. |
238 | * |
239 | * has only effect if ShowKeepCheckBox is set in the constructor |
240 | */ |
241 | void setKeepPassword( bool b ); |
242 | |
243 | /** |
244 | * Sets the username field read-only and sets the |
245 | * focus to the password field. |
246 | * |
247 | * this can also be set by passing UsernameReadOnly as flag in the constructor |
248 | * |
249 | * @param readOnly true to set the user field to read-only |
250 | */ |
251 | void setUsernameReadOnly( bool readOnly ); |
252 | |
253 | /** |
254 | * Presets the password. |
255 | * @param password the password to set |
256 | */ |
257 | void setPassword( const QString& password ); |
258 | |
259 | /** |
260 | * Presets a number of login+password pairs that the user can choose from. |
261 | * The passwords can be empty if you simply want to offer usernames to choose from. |
262 | * |
263 | * This require the flag ShowUnernameLine to be set in the constructoe, and not the flag UsernameReadOnly |
264 | * @param knownLogins map of known logins: the keys are usernames, the values are passwords. |
265 | */ |
266 | void setKnownLogins( const QMap<QString, QString>& knownLogins ); |
267 | |
268 | /** |
269 | * @internal |
270 | */ |
271 | void accept(); |
272 | |
273 | Q_SIGNALS: |
274 | /** |
275 | * emitted when the dialog has been accepted |
276 | * @param password the entered password |
277 | * @param keep true if the "remember password" checkbox was checked, false otherwise. false if ShowKeepPassword was not set in the constructor |
278 | */ |
279 | void gotPassword( const QString& password , bool keep ); |
280 | |
281 | /** |
282 | * emitted when the dialog has been accepted, and ShowUsernameLine was set on the constructor |
283 | * @param username the entered username |
284 | * @param password the entered password |
285 | * @param keep true if the "remember password" checkbox was checked, false otherwise. false if ShowKeepPassword was not set in the constructor |
286 | */ |
287 | void gotUsernameAndPassword( const QString& username, const QString& password , bool keep ); |
288 | |
289 | protected: |
290 | /** |
291 | * Virtual function that can be overridden to provide password |
292 | * checking in derived classes. It should return @p true if the |
293 | * password is valid, @p false otherwise. |
294 | */ |
295 | virtual bool checkPassword(); |
296 | |
297 | |
298 | private: |
299 | Q_PRIVATE_SLOT(d, void actuallyAccept()) |
300 | Q_PRIVATE_SLOT(d, void activated( const QString& userName )) |
301 | Q_PRIVATE_SLOT(d, void updateFields()) |
302 | |
303 | private: |
304 | class KPasswordDialogPrivate; |
305 | friend class KPasswordDialogPrivate; |
306 | KPasswordDialogPrivate* const d; |
307 | |
308 | Q_DISABLE_COPY(KPasswordDialog) |
309 | }; |
310 | |
311 | Q_DECLARE_OPERATORS_FOR_FLAGS(KPasswordDialog::KPasswordDialogFlags) |
312 | |
313 | #endif |
314 | |