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 */
56class KDEUI_EXPORT KPasswordDialog : public KDialog
57{
58 Q_OBJECT
59
60public:
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 addCommentLine( const QString& label, const QString& comment );
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
273Q_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
289protected:
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
298private:
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
303private:
304 class KPasswordDialogPrivate;
305 friend class KPasswordDialogPrivate;
306 KPasswordDialogPrivate* const d;
307
308 Q_DISABLE_COPY(KPasswordDialog)
309};
310
311Q_DECLARE_OPERATORS_FOR_FLAGS(KPasswordDialog::KPasswordDialogFlags)
312
313#endif
314