1// vi: ts=8 sts=4 sw=4
2/*
3 This file is part of the KDE libraries
4 SPDX-FileCopyrightText: 1998 Pietro Iglio <iglio@fub.it>
5 SPDX-FileCopyrightText: 1999, 2000 Geert Jansen <jansen@kde.org>
6 SPDX-FileCopyrightText: 2004, 2005 Andrew Coles <andrew_coles@yahoo.co.uk>
7 SPDX-FileCopyrightText: 2006, 2007 Olivier Goffart <ogoffart @ kde.org>
8 SPDX-FileCopyrightText: 2015 Elvis Angelaccio <elvis.angelaccio@kde.org>
9
10 SPDX-License-Identifier: LGPL-2.0-only
11*/
12#ifndef KNEWPASSWORDWIDGET_H
13#define KNEWPASSWORDWIDGET_H
14
15#include <KPassword>
16#include <KPasswordLineEdit>
17#include <QWidget>
18#include <memory>
19
20#include <kwidgetsaddons_export.h>
21
22/*!
23 * \class KNewPasswordWidget
24 * \inmodule KWidgetsAddons
25 *
26 * \brief A password input widget.
27 *
28 * This widget allows the user to enter a new password.
29 *
30 * The password has to be entered twice to check if the passwords
31 * match. A hint about the strength of the entered password is also
32 * shown.
33 *
34 * In order to embed this widget in your custom password dialog,
35 * you may want to connect to the passwordStatus() signal.
36 * This way you can e.g. disable the OK button if the passwords
37 * don't match, warn the user if the password is too weak, and so on.
38 *
39 * \section1 Usage Example
40 * \section2 Setup
41 *
42 * \code
43 * KNewPasswordWidget *m_passwordWidget = new KNewPasswordWidget(this);
44 * // set a background warning color (taken from the current color scheme)
45 * KColorScheme colorScheme(QPalette::Active, KColorScheme::View);
46 * m_passwordWidget->setBackgroundWarningColor(colorScheme.background(KColorScheme::NegativeBackground).color());
47 * // listen to password status updates
48 * connect(m_passwordWidget, &KNewPasswordWidget::passwordStatusChanged, this, &MyCustomDialog::slotPasswordStatusChanged);
49 * ...
50 * \endcode
51 *
52 * \section2 Update your custom dialog
53 *
54 * TODO qdoc
55 * @snippet knewpasswordwidget_test.cpp update_custom_dialog
56 *
57 * \section2 Accept your custom dialog
58 *
59 * TODO qdoc
60 * @snippet knewpasswordwidget_test.cpp accept_custom_dialog
61 *
62 * \since 5.16
63 */
64class KWIDGETSADDONS_EXPORT KNewPasswordWidget : public QWidget
65{
66 Q_OBJECT
67
68 /*!
69 * \property KNewPasswordWidget::passwordStatus
70 */
71 Q_PROPERTY(PasswordStatus passwordStatus READ passwordStatus)
72
73 /*!
74 * \property KNewPasswordWidget::allowEmptyPasswords
75 */
76 Q_PROPERTY(bool allowEmptyPasswords READ allowEmptyPasswords WRITE setAllowEmptyPasswords)
77
78 /*!
79 * \property KNewPasswordWidget::minimumPasswordLength
80 */
81 Q_PROPERTY(int minimumPasswordLength READ minimumPasswordLength WRITE setMinimumPasswordLength)
82
83 /*!
84 * \property KNewPasswordWidget::maximumPasswordLength
85 */
86 Q_PROPERTY(int maximumPasswordLength READ maximumPasswordLength WRITE setMaximumPasswordLength)
87
88 /*!
89 * \property KNewPasswordWidget::reasonablePasswordLength
90 */
91 Q_PROPERTY(int reasonablePasswordLength READ reasonablePasswordLength WRITE setReasonablePasswordLength)
92
93 /*!
94 * \property KNewPasswordWidget::passwordStrengthWarningLevel
95 */
96 Q_PROPERTY(int passwordStrengthWarningLevel READ passwordStrengthWarningLevel WRITE setPasswordStrengthWarningLevel)
97
98 /*!
99 * \property KNewPasswordWidget::backgroundWarningColor
100 */
101 Q_PROPERTY(QColor backgroundWarningColor READ backgroundWarningColor WRITE setBackgroundWarningColor)
102
103 /*!
104 * \property KNewPasswordWidget::passwordStrengthMeterVisible
105 */
106 Q_PROPERTY(bool passwordStrengthMeterVisible READ isPasswordStrengthMeterVisible WRITE setPasswordStrengthMeterVisible)
107#if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(6, 0)
108 /*!
109 * \property KNewPasswordWidget::revealPasswordAvailable
110 * \since 5.31
111 * \deprecated[6.0]
112 */
113 Q_PROPERTY(bool revealPasswordAvailable READ isRevealPasswordAvailable WRITE setRevealPasswordAvailable)
114#endif
115 /*!
116 * \property KNewPasswordWidget::revealPasswordMode
117 */
118 Q_PROPERTY(KPassword::RevealMode revealPasswordMode READ revealPasswordMode WRITE setRevealPasswordMode)
119
120public:
121 /*!
122 * Status of the password being typed in the widget.
123 * \value EmptyPasswordNotAllowed Both passwords fields empty, but minimum length > 0.
124 * \value PasswordTooShort Password length is too low.
125 * \value PasswordNotVerified Password and verification password don't match.
126 * \value WeakPassword Passwords match but the strength level is not enough.
127 * \value StrongPassword Passwords match and the strength level is good.
128 */
129 enum PasswordStatus {
130 EmptyPasswordNotAllowed,
131 PasswordTooShort,
132 PasswordNotVerified,
133 WeakPassword,
134 StrongPassword,
135 };
136 Q_ENUM(PasswordStatus)
137
138 /*!
139 * This enum describe when the reveal password button is visible.
140 * \since 6.0
141 *
142 * \value OnlyNew Display the button when entering a new password, but doesn't let you see a previously entered password. This is the default.
143 * \value Never Never display the reveal button.
144 * \value Always Always display the reveal button. Usefull in a password manager for example.
145 */
146 enum class RevealPasswordMode {
147 OnlyNew,
148 Never,
149 Always,
150 };
151 Q_ENUM(RevealPasswordMode)
152
153 /*!
154 * Constructs a password widget.
155 *
156 * \a parent Passed to lower level constructor.
157 */
158 explicit KNewPasswordWidget(QWidget *parent = nullptr);
159
160 ~KNewPasswordWidget() override;
161
162 /*!
163 * The current status of the password in the widget.
164 */
165 PasswordStatus passwordStatus() const;
166
167 /*!
168 * Allow empty passwords?
169 *
170 * Returns \c true if minimumPasswordLength() == 0
171 */
172 bool allowEmptyPasswords() const;
173
174 /*!
175 * Minimum acceptable password length.
176 */
177 int minimumPasswordLength() const;
178
179 /*!
180 * Maximum acceptable password length.
181 */
182 int maximumPasswordLength() const;
183
184 /*!
185 * Password length that is expected to be reasonably safe.
186 */
187 int reasonablePasswordLength() const;
188
189 /*!
190 * Password strength level below which a warning is given
191 */
192 int passwordStrengthWarningLevel() const;
193
194 /*!
195 * The color used as warning for the verification password field's background.
196 */
197 QColor backgroundWarningColor() const;
198
199 /*!
200 * Whether the password strength meter is visible.
201 */
202 bool isPasswordStrengthMeterVisible() const;
203
204#if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(6, 0)
205 /*!
206 * Whether the visibility trailing action in the line edit is visible.
207 * \since 5.31
208 * \deprecated[6.0]
209 */
210 [[deprecated("Use revealPasswordMode instead.")]] bool isRevealPasswordAvailable() const;
211#endif
212
213 /*!
214 * Whether the visibility trailing action in the line edit is visible.
215 * \since 6.0
216 */
217 KPassword::RevealMode revealPasswordMode() const;
218
219 /*!
220 * Returns the password entered.
221 *
222 * \note Only returns meaningful data when passwordStatus
223 * is either WeakPassword or StrongPassword.
224 */
225 QString password() const;
226
227public Q_SLOTS:
228
229 /*!
230 * Allow empty passwords? - Default: true
231 *
232 * same as setMinimumPasswordLength( allowed ? 0 : 1 )
233 */
234 void setAllowEmptyPasswords(bool allowed);
235
236 /*!
237 * Minimum acceptable password length.
238 *
239 * Default: 0
240 *
241 * \a minLength The new minimum password length
242 */
243 void setMinimumPasswordLength(int minLength);
244
245 /*!
246 * Maximum acceptable password length.
247 *
248 * \a maxLength The new maximum password length.
249 */
250 void setMaximumPasswordLength(int maxLength);
251
252 /*!
253 * Password length that is expected to be reasonably safe.
254 * The value is guaranteed to be in the range from 1 to maximumPasswordLength().
255 *
256 * Used to compute the strength level
257 *
258 * Default: 8 - the standard UNIX password length
259 *
260 * \a reasonableLength The new reasonable password length.
261 */
262 void setReasonablePasswordLength(int reasonableLength);
263
264 /*!
265 * Set the password strength level below which a warning is given
266 * The value is guaranteed to be in the range from 0 to 99. Empty passwords score 0;
267 * non-empty passwords score up to 100, depending on their length and whether they
268 * contain numbers, mixed case letters and punctuation.
269 *
270 * Default: 1 - warn if the password has no discernible strength whatsoever
271 *
272 * \a warningLevel The level below which a warning should be given.
273 */
274 void setPasswordStrengthWarningLevel(int warningLevel);
275
276 /*!
277 * When the verification password does not match, the background color
278 * of the verification field is set to @p color. As soon as the passwords match,
279 * the original color of the verification field is restored.
280 */
281 void setBackgroundWarningColor(const QColor &color);
282
283 /*!
284 * Whether to show the password strength meter (label and progress bar).
285 * Default is true.
286 */
287 void setPasswordStrengthMeterVisible(bool visible);
288
289#if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(6, 0)
290 /*!
291 * Whether to show the visibility trailing action in the line edit.
292 * Default is true. This can be used to honor the lineedit_reveal_password
293 * kiosk key, for example:
294 * \code
295 * passwordWidget.setRevealPasswordAvailable(KAuthorized::authorize(QStringLiteral("lineedit_reveal_password")));
296 * \endcode
297 * \since 5.31
298 * \deprecated[6.0]
299 */
300 [[deprecated("Use setRevealPasswordMode instead.")]] void setRevealPasswordAvailable(bool reveal);
301#endif
302
303 /*!
304 * Set when the reveal password button will be visible.
305 *
306 * The default is RevealPasswordMode::OnlyNew and the reveal password button will
307 * only be visible when entering a new password.
308 *
309 * This can be used to honor the lineedit_reveal_password kiosk key, for example:
310 *
311 * \code
312 * if (KAuthorized::authorize(QStringLiteral("lineedit_reveal_password"))) {
313 * newPasswordWidget.setRevealPasswordMode(KPassword::RevealMode::OnlyNew);
314 * } else {
315 * newPasswordWidget.setRevealPasswordMode(KPassword::RevealMode::Never);
316 * }
317 * \endcode
318 * \since 6.0
319 */
320 void setRevealPasswordMode(KPassword::RevealMode revealPasswordMode);
321
322Q_SIGNALS:
323
324 /*!
325 * Notify about the current status of the password being typed.
326 */
327 void passwordStatusChanged();
328
329private:
330 std::unique_ptr<class KNewPasswordWidgetPrivate> const d;
331
332 Q_DISABLE_COPY(KNewPasswordWidget)
333};
334
335#endif // KNEWPASSWORDWIDGET_H
336

source code of kwidgetsaddons/src/knewpasswordwidget.h