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
9 SPDX-License-Identifier: LGPL-2.0-only
10*/
11#ifndef KNEWPASSWORDDIALOG_H
12#define KNEWPASSWORDDIALOG_H
13
14#include <KPassword>
15#include <QDialog>
16#include <memory>
17
18#include <kwidgetsaddons_export.h>
19
20class QWidget;
21
22/*!
23 * \class KNewPasswordDialog
24 * \inmodule KWidgetsAddons
25 *
26 * \brief A password input dialog.
27 *
28 * This dialog asks 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 * \section1 Usage Example
35 * \section2 Asynchronous
36 *
37 * \code
38 * KNewPasswordDialog *dlg = new KNewPasswordDialog( parent );
39 * dlg->setPrompt(i18n("Enter a password"));
40 * connect(dlg, &KNewPasswordDialog::newPassword, this, [this](const QString &pass) { setPassword(pass); });
41 * connect(dlg, &QDialog::rejected, this, [this]() { slotCancel(); });
42 * dlg->show();
43 * \endcode
44 *
45 * \section2 Synchronous
46 *
47 * \code
48 * KNewPasswordDialog dlg(parent);
49 * dlg.setPrompt(i18n("Enter a password"));
50 * if(dlg.exec()) {
51 * setPassword(dlg.password());
52 * }
53 * \endcode
54 *
55 * \image knewpassworddialog.png "KNewPasswordDialog"
56 */
57class KWIDGETSADDONS_EXPORT KNewPasswordDialog : public QDialog
58{
59 Q_OBJECT
60
61 /*!
62 * \property KNewPasswordDialog::revealPasswordMode
63 * \since 6.0
64 */
65 Q_PROPERTY(KPassword::RevealMode revealPasswordMode READ revealPasswordMode WRITE setRevealPasswordMode)
66
67public:
68 /*!
69 * Constructs a password dialog.
70 *
71 * \a parent Passed to lower level constructor.
72 */
73 explicit KNewPasswordDialog(QWidget *parent = nullptr);
74
75 ~KNewPasswordDialog() override;
76
77 /*!
78 * Sets the password prompt.
79 */
80 void setPrompt(const QString &prompt);
81
82 /*!
83 * Returns the password prompt.
84 */
85 QString prompt() const;
86
87 /*!
88 * Sets the icon that appears next to the prompt in the dialog. The default icon represents a simple key.
89 * \since 5.63
90 */
91 void setIcon(const QIcon &icon);
92
93 /*!
94 * Returns the icon that appears next to the prompt in the dialog. The default icon represents a simple key.
95 * \since 5.63
96 */
97 QIcon icon() const;
98
99 /*!
100 * Allow empty passwords? - Default: true
101 *
102 * same as setMinimumPasswordLength( allowed ? 0 : 1 )
103 */
104 void setAllowEmptyPasswords(bool allowed);
105
106 /*!
107 * Allow empty passwords?
108 *
109 * Returns \c true if minimumPasswordLength() == 0
110 */
111 bool allowEmptyPasswords() const;
112
113 /*!
114 * Minimum acceptable password length.
115 *
116 * Default: 0
117 *
118 * \a minLength The new minimum password length
119 */
120 void setMinimumPasswordLength(int minLength);
121
122 /*!
123 * Minimum acceptable password length.
124 */
125 int minimumPasswordLength() const;
126
127 /*!
128 * Maximum acceptable password length.
129 *
130 * \a maxLength The new maximum password length.
131 */
132 void setMaximumPasswordLength(int maxLength);
133
134 /*!
135 * Maximum acceptable password length.
136 */
137 int maximumPasswordLength() const;
138
139 /*!
140 * Password length that is expected to be reasonably safe.
141 *
142 * Used to compute the strength level
143 *
144 * Default: 8 - the standard UNIX password length
145 *
146 * \a reasonableLength The new reasonable password length.
147 */
148 void setReasonablePasswordLength(int reasonableLength);
149
150 /*!
151 * Password length that is expected to be reasonably safe.
152 */
153 int reasonablePasswordLength() const;
154
155 /*!
156 * Set the password strength level below which a warning is given
157 * Value is in the range 0 to 99. Empty passwords score 0;
158 * non-empty passwords score up to 100, depending on their length and whether they
159 * contain numbers, mixed case letters and punctuation.
160 *
161 * Default: 1 - warn if the password has no discernible strength whatsoever
162 *
163 * \a warningLevel The level below which a warning should be given.
164 */
165 void setPasswordStrengthWarningLevel(int warningLevel);
166
167 /*!
168 * Password strength level below which a warning is given
169 */
170 int passwordStrengthWarningLevel() const;
171
172 /*!
173 * When the verification password does not match, the background color
174 * of the verification field is set to \a color. As soon as the passwords match,
175 * the original color of the verification field is restored.
176 *
177 * Default: the background color from the current theme.
178 * \since 5.17
179 */
180 void setBackgroundWarningColor(const QColor &color);
181
182 /*!
183 * The color used as warning for the verification password field's background.
184 * \since 5.17
185 */
186 QColor backgroundWarningColor() const;
187
188 /*!
189 * Returns the password entered.
190 *
191 * \note Only has meaningful data after accept has been called
192 * if you want to access the password from a subclass use
193 * checkAndGetPassword()
194 */
195 QString password() const;
196
197#if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(6, 0)
198 /*!
199 * Whether to show the visibility trailing action in the line edit.
200 * Default is true. This can be used to honor the lineedit_reveal_password
201 * kiosk key, for example:
202 * \code
203 * passwordDialog.setRevealPasswordAvailable(KAuthorized::authorize(QStringLiteral("lineedit_reveal_password")));
204 * \endcode
205 * \deprecated[6.0]
206 * \since 5.31
207 */
208 [[deprecated("Use setRevealPasswordMode instead.")]] void setRevealPasswordAvailable(bool reveal);
209
210 /*!
211 * Whether the visibility trailing action in the line edit is visible.
212 * \deprecated[6.0]
213 * \since 5.31
214 */
215 [[deprecated("Use revealPasswordMode instead.")]] bool isRevealPasswordAvailable() const;
216#endif
217
218 /*!
219 * Whether the visibility trailing action in the line edit is visible.
220 * \since 6.0
221 */
222 KPassword::RevealMode revealPasswordMode() const;
223
224 /*!
225 * Set when the reveal password button will be visible.
226 *
227 * The default is RevealPasswordMode::OnlyNew and the reveal password button will
228 * only be visible when entering a new password.
229 *
230 * This can be used to honor the lineedit_reveal_password kiosk key, for example:
231 *
232 * \code
233 * if (KAuthorized::authorize(QStringLiteral("lineedit_reveal_password"))) {
234 * newPasswordDialog.setRevealPasswordMode(KPassword::RevealMode::OnlyNew);
235 * } else {
236 * newPasswordDialog.setRevealPasswordMode(KPassword::RevealMode::Never);
237 * }
238 * \endcode
239 * \since 6.0
240 */
241 void setRevealPasswordMode(KPassword::RevealMode revealPasswordMode);
242
243 void accept() override;
244
245protected:
246 /*!
247 * Virtual function that can be overridden to provide password
248 * checking in derived classes. It should return \a true if the
249 * password is valid, \a false otherwise.
250 */
251 virtual bool checkPassword(const QString &);
252
253 /*!
254 * Checks input password.
255 * If the password is right, returns true
256 * and fills pwd with the password.
257 * Otherwise returns false and pwd will be null.
258 * \since 4.2
259 */
260 bool checkAndGetPassword(QString *pwd);
261
262Q_SIGNALS:
263
264 /*!
265 * The dialog has been accepted, and the new password is \a password
266 */
267 void newPassword(const QString &password);
268
269private:
270 std::unique_ptr<class KNewPasswordDialogPrivate> const d;
271};
272
273#endif // KNEWPASSWORDDIALOG_H
274

source code of kwidgetsaddons/src/knewpassworddialog.h