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