1// vi: ts=8 sts=4 sw=4
2/* This file is part of the KDE libraries
3 Copyright (C) 1998 Pietro Iglio <iglio@fub.it>
4 Copyright (C) 1999,2000 Geert Jansen <jansen@kde.org>
5 Copyright (C) 2004,2005 Andrew Coles <andrew_coles@yahoo.co.uk>
6 Copyright (C) 2006,2007 Olivier Goffart <ogoffart @ kde.org>
7
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public
10 License version 2 as published by the Free Software Foundation.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22#ifndef KNEWPASSWORDDIALOG_H
23#define KNEWPASSWORDDIALOG_H
24
25// ### KDE 5: remove
26#include <QtGui/QLineEdit>
27
28#include <kdialog.h>
29
30class QWidget;
31
32
33/**
34 * @short A password input dialog.
35 *
36 * This dialog asks the user to enter a new password.
37 *
38 * The password has to be entered twice to check if the passwords
39 * match. A hint about the strength of the entered password is also
40 * shown.
41 *
42 * \section usage Usage Example
43 * \subsection asynchronous Asynchronous
44 *
45 * \code
46 * KNewPasswordDialog *dlg = new KNewPasswordDialog( parent );
47 * dlg->setPrompt( i18n( "Enter a password" ) );
48 * connect( dlg, SIGNAL( newPassword(QString) ) , this, SLOT( setPassword(QString) ) );
49 * connect( dlg, SIGNAL( rejected() ) , this, SLOT( slotCancel() ) );
50 * dlg->show();
51 * \endcode
52 *
53 * \subsection synchronous Synchronous
54 *
55 * \code
56 * KNewPasswordDialog dlg( parent );
57 * dlg.setPrompt( i18n( "Enter a password" ) );
58 * if( dlg.exec() )
59 * setPassword( dlg.password() );
60 * \endcode
61 *
62 * \image html knewpassworddialog.png "KDE New Password Dialog"
63 *
64 * @author Geert Jansen <jansen@kde.org>
65 * @author Olivier Goffart <ogoffart@kde.org>
66 */
67
68class KDEUI_EXPORT KNewPasswordDialog
69 : public KDialog
70{
71 Q_OBJECT
72
73public:
74 /**
75 * Constructs a password dialog.
76 *
77 * @param parent Passed to lower level constructor.
78 */
79 explicit KNewPasswordDialog(QWidget *parent=0);
80
81 /**
82 * Destructs the password dialog.
83 */
84 virtual ~KNewPasswordDialog();
85
86 /**
87 * Sets the password prompt.
88 */
89 void setPrompt(const QString &prompt);
90
91 /**
92 * Returns the password prompt.
93 */
94 QString prompt() const;
95
96 /**
97 * Sets the pixmap that appears next to the prompt in the dialog. The default pixmap represent a simple key.
98 *
99 * the recommended size is KIconLoader::SizeHuge
100 */
101 void setPixmap(const QPixmap&);
102
103 /**
104 * Returns the pixmap that appears next to the prompt in the dialog
105 */
106 QPixmap pixmap() const;
107
108 /**
109 * Allow empty passwords? - Default: true
110 *
111 * same as setMinimumPasswordLength( allowed ? 0 : 1 )
112 */
113 void setAllowEmptyPasswords(bool allowed);
114
115 /**
116 * Allow empty passwords?
117 *
118 * @return true if minimumPasswordLength() == 0
119 */
120 bool allowEmptyPasswords() const;
121
122 /**
123 * Minimum acceptable password length.
124 *
125 * Default: 0
126 *
127 * @param minLength The new minimum password length
128 */
129 void setMinimumPasswordLength(int minLength);
130
131 /**
132 * Minimum acceptable password length.
133 */
134 int minimumPasswordLength() const;
135
136 /**
137 * Maximum acceptable password length.
138 *
139 * @param maxLength The new maximum password length.
140 */
141 void setMaximumPasswordLength(int maxLength);
142
143 /**
144 * Maximum acceptable password length.
145 */
146 int maximumPasswordLength() const;
147
148 /**
149 * Password length that is expected to be reasonably safe.
150 *
151 * Used to compute the strength level
152 *
153 * Default: 8 - the standard UNIX password length
154 *
155 * @param reasonableLength The new reasonable password length.
156 */
157 void setReasonablePasswordLength(int reasonableLength);
158
159 /**
160 * Password length that is expected to be reasonably safe.
161 */
162 int reasonablePasswordLength() const;
163
164 /**
165 * Set the password strength level below which a warning is given
166 * Value is in the range 0 to 99. Empty passwords score 0;
167 * non-empty passwords score up to 100, depending on their length and whether they
168 * contain numbers, mixed case letters and punctuation.
169 *
170 * Default: 1 - warn if the password has no discernable strength whatsoever
171 * @param warningLevel The level below which a warning should be given.
172 */
173 void setPasswordStrengthWarningLevel(int warningLevel);
174
175 /**
176 * Password strength level below which a warning is given
177 */
178 int passwordStrengthWarningLevel() const;
179
180 /**
181 * Returns the password entered.
182 * @note Only has meaningful data after accept has been called
183 * if you want to access the password from a subclass use
184 * checkAndGetPassword()
185 */
186 QString password() const;
187
188 /**
189 * @internal
190 */
191 virtual void accept();
192
193protected:
194
195 /**
196 * Virtual function that can be overridden to provide password
197 * checking in derived classes. It should return @p true if the
198 * password is valid, @p false otherwise.
199 */
200 virtual bool checkPassword(const QString &) ;
201
202 /**
203 * Checks input password.
204 * If the password is right, returns true
205 * and fills pwd with the password.
206 * Otherwise returns false and pwd will be null.
207 * @since 4.2
208 */
209 bool checkAndGetPassword(QString *pwd);
210
211Q_SIGNALS:
212
213 /**
214 * The dialog has been accepted, and the new password is @p password
215 */
216 void newPassword(const QString &password);
217
218
219private:
220 class KNewPasswordDialogPrivate;
221 KNewPasswordDialogPrivate* const d;
222
223 Q_PRIVATE_SLOT( d, void _k_textChanged() )
224};
225
226#endif // KNEWPASSWORDDIALOG_H
227
228// kate: space-indent on; indent-width 4; encoding utf-8; replace-tabs on;
229