KWidgetsAddons

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

KDE's Doxygen guidelines are available online.