1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
4 SPDX-FileCopyrightText: 2000 Dawit Alemayehu <adawit@kde.org>
5 SPDX-FileCopyrightText: 2007 Olivier Goffart <ogoffart at kde.org>
6 SPDX-FileCopyrightText: 2020 Harald Sitter <sitter@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KPASSWORDDIALOG_H
12#define KPASSWORDDIALOG_H
13
14#include <KPassword>
15#include <QDialog>
16#include <QDialogButtonBox>
17#include <memory>
18
19#include <kwidgetsaddons_export.h>
20
21/*!
22 * \class KPasswordDialog
23 * \inmodule KWidgetsAddons
24 *
25 * \brief A dialog for requesting a password and optionally a login from the end user.
26 *
27 * \section1 Usage Example
28 *
29 * Requesting a simple password, asynchronous
30 *
31 * \code
32 * KPasswordDialog *dlg = new KPasswordDialog(parent);
33 * dlg->setPrompt(i18n("Enter a password"));
34 * connect(dlg, &KPasswordDialog::gotPassword,
35 * this, [this](const QString &password) { setPassword(password); });
36 * connect(dlg, &QDialog::rejected, this, [this]() { slotCancel(); });
37 * dlg->show();
38 * \endcode
39 *
40 * Requesting a login and a password, synchronous
41 *
42 * \code
43 * KPasswordDialog dlg(parent, KPasswordDialog::ShowUsernameLine);
44 * dlg.setPrompt(i18n("Enter a login and a password"));
45 * if(!dlg.exec()) {
46 * return; //the user canceled
47 * }
48 * use(dlg.username(), dlg.password());
49 * \endcode
50 *
51 * \image kpassworddialog.png "KPasswordDialog"
52 */
53class KWIDGETSADDONS_EXPORT KPasswordDialog : public QDialog
54{
55 Q_OBJECT
56
57public:
58 /*!
59 * \value NoFlags
60 * \value ShowKeepPassword If this flag is set, the "keep this password" checkbox will been shown, otherwise, it will not be shown and keepPassword will
61 * have no effect.
62 * \value ShowUsernameLine If this flag is set, there will be an additional line to let the user enter his login, otherwise, only the password line will be
63 * shown.
64 * \value UsernameReadOnly If this flag is set, the login lineedit will be in read only mode.
65 * \value[since 4.1] ShowAnonymousLoginCheckBox If this flag is set, the Anonymous Login checkbox will be displayed
66 * \value[since 4.1] ShowDomainLine If this flag is set, there will be an additional line to let the user enter the domain.
67 * \value[since 4.1] DomainReadOnly If this flag is set, the domain lineedit will be in read only mode.
68 */
69 enum KPasswordDialogFlag {
70 NoFlags = 0x00,
71 ShowKeepPassword = 0x01,
72 ShowUsernameLine = 0x02,
73 UsernameReadOnly = 0x04,
74 ShowAnonymousLoginCheckBox = 0x08,
75 ShowDomainLine = 0x10,
76 DomainReadOnly = 0x20,
77 };
78 Q_DECLARE_FLAGS(KPasswordDialogFlags, KPasswordDialogFlag)
79
80 /*!
81 * \value UnknownError
82 * \value UsernameError A problem with the user name as entered
83 * \value PasswordError Incorrect password
84 * \value FatalError Error preventing further attempts, will result in disabling most of the interface
85 * \value[since 4.1] DomainError A problem with the domain as entered
86 */
87 enum ErrorType {
88 UnknownError = 0,
89 UsernameError,
90 PasswordError,
91 FatalError,
92 DomainError,
93 };
94
95 /*!
96 * create a password dialog
97 *
98 * \a parent the parent widget
99 *
100 * \a flags a set of KPasswordDialogFlag flags
101 */
102 explicit KPasswordDialog(QWidget *parent = nullptr, const KPasswordDialogFlags &flags = KPasswordDialog::NoFlags);
103
104 ~KPasswordDialog() override;
105
106 /*!
107 * Sets the prompt to show to the user.
108 *
109 * \a prompt instructional text to be shown.
110 */
111 void setPrompt(const QString &prompt);
112
113 /*!
114 * Returns the prompt
115 */
116 QString prompt() const;
117
118 /*!
119 * Set the icon that appears next to the prompt.
120 * \since 5.63
121 */
122 void setIcon(const QIcon &icon);
123
124 /*!
125 * Returns the icon that appears next to the prompt.
126 */
127 QIcon icon() const;
128
129 /*!
130 * Adds a comment line to the dialog.
131 *
132 * This function allows you to add one additional comment
133 * line to this widget. Calling this function after a
134 * comment has already been added will not have any effect.
135 *
136 * \a label label for comment (ex:"Command:")
137 *
138 * \a comment the actual comment text.
139 */
140 void addCommentLine(const QString &label, const QString &comment);
141
142 /*!
143 * Shows an error message in the dialog box. Prevents having to show a dialog-on-a-dialog.
144 *
145 * \a message the error message to show
146 */
147 void showErrorMessage(const QString &message, const ErrorType type = PasswordError);
148
149 /*!
150 * Returns the password entered by the user.
151 */
152 QString password() const;
153
154 /*!
155 * set the default username.
156 */
157 void setUsername(const QString &);
158
159 /*!
160 * Returns the username entered by the user.
161 */
162 QString username() const;
163
164 /*!
165 * set the default domain.
166 * \since 4.1
167 */
168 void setDomain(const QString &);
169
170 /*!
171 * Returns the domain entered by the user.
172 * \since 4.1
173 */
174 QString domain() const;
175
176 /*!
177 * set anonymous mode (all other fields will be grayed out)
178 * \since 4.1
179 */
180 void setAnonymousMode(bool anonymous);
181
182 /*!
183 * Returns whether anonymous mode has been selected.
184 * \since 4.1
185 */
186 bool anonymousMode() const;
187
188 /*!
189 * Determines whether supplied authorization should
190 * persist even after the application has been closed.
191 *
192 * this is set with the check password checkbox is the ShowKeepCheckBox flag
193 * is set in the constructor, if it is not set, this function return false
194 *
195 * Returns whether to keep the password
196 */
197 bool keepPassword() const;
198
199 /*!
200 * Check or uncheck the "keep password" checkbox.
201 * This can be used to check it before showing the dialog, to tell
202 * the user that the password is stored already (e.g. in the wallet).
203 * enableKeep must have been set to true in the constructor.
204 *
205 * has only effect if ShowKeepCheckBox is set in the constructor
206 */
207 void setKeepPassword(bool b);
208
209 /*!
210 * Sets the username field read-only and sets the
211 * focus to the password field.
212 *
213 * this can also be set by passing UsernameReadOnly as flag in the constructor
214 *
215 * \a readOnly true to set the user field to read-only
216 */
217 void setUsernameReadOnly(bool readOnly);
218
219 /*!
220 * Presets the password.
221 *
222 * If the password is not empty, the ability to show the password will not be available.
223 *
224 * \a password the password to set
225 */
226 void setPassword(const QString &password);
227
228 /*!
229 * Presets a number of login+password pairs that the user can choose from.
230 *
231 * The passwords can be empty if you simply want to offer usernames to choose from.
232 *
233 * This require the flag ShowUsernameLine to be set in the constructoe, and not the flag UsernameReadOnly
234 *
235 * \a knownLogins map of known logins: the keys are usernames, the values are passwords.
236 */
237 void setKnownLogins(const QMap<QString, QString> &knownLogins);
238
239 void accept() override;
240
241 /*!
242 * Returns the button box used in the dialog.
243 * This can be used to add new buttons.
244 *
245 * \since 5.0
246 */
247 QDialogButtonBox *buttonBox() const;
248
249 /*!
250 * Sets contextual help for the username input field. This displays a
251 * somewhat visual hint in the UI giving very visible access to a whats-this
252 * style input description for the user name line. This is particularly useful
253 * when the user name may require or support special input syntax.
254 * For example windows-like auth dialogs supports multiple different logon
255 * name syntax.
256 * \since 5.76
257 */
258 void setUsernameContextHelp(const QString &help);
259
260#if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(6, 0)
261 /*!
262 * Whether to show the visibility trailing action in the line edit.
263 * Default is @c true. This can be used to honor the lineedit_reveal_password
264 * kiosk key, for example:
265 * \code
266 * dlg->setRevealPasswordAvailable(KAuthorized::authorize(QStringLiteral("lineedit_reveal_password")));
267 * \endcode
268 * \deprecated[6.0]
269 * \since 5.84
270 */
271 [[deprecated("Use setRevealPasswordMode instead.")]] void setRevealPasswordAvailable(bool reveal);
272
273 /*!
274 * Whether the visibility trailing action in the line edit is visible.
275 * \since 5.84
276 * \deprecated[6.0]
277 */
278 [[deprecated("Use revealPasswordMode instead.")]] bool isRevealPasswordAvailable() const;
279#endif
280
281 /*!
282 * Return when the reveal password button is visible.
283 * \since 6.0
284 */
285 KPassword::RevealMode revealPasswordMode() const;
286
287 /*!
288 * Set when the reveal password button will be visible.
289 *
290 * The default is RevealMode::OnlyNew and the reveal password button will
291 * only be visible when entering a new password.
292 *
293 * This can be used to honor the lineedit_reveal_password kiosk key, for example:
294 *
295 * \code
296 * if (KAuthorized::authorize(QStringLiteral("lineedit_reveal_password"))) {
297 * passwordDialog.setRevealPasswordMode(KPassword::RevealMode::OnlyNew);
298 * } else {
299 * passwordDialog.setRevealPasswordMode(KPassword::RevealMode::Never);
300 * }
301 * \endcode
302 * \since 6.0
303 */
304 void setRevealPasswordMode(KPassword::RevealMode revealPasswordMode);
305
306Q_SIGNALS:
307 /*!
308 * emitted when the dialog has been accepted
309 *
310 * \a password the entered password
311 *
312 * \a keep true if the "remember password" checkbox was checked, false otherwise. false if ShowKeepPassword was not set in the constructor
313 */
314 void gotPassword(const QString &password, bool keep);
315
316 /*!
317 * emitted when the dialog has been accepted, and ShowUsernameLine was set on the constructor
318 *
319 * \a username the entered username
320 *
321 * \a password the entered password
322 *
323 * \a keep true if the "remember password" checkbox was checked, false otherwise. false if ShowKeepPassword was not set in the constructor
324 */
325 void gotUsernameAndPassword(const QString &username, const QString &password, bool keep);
326
327protected:
328 /*!
329 * Virtual function that can be overridden to provide password
330 * checking in derived classes. It should return \c true if the
331 * password is valid, \c false otherwise.
332 */
333 virtual bool checkPassword();
334
335private:
336 friend class KPasswordDialogPrivate;
337 std::unique_ptr<class KPasswordDialogPrivate> const d;
338
339 Q_DISABLE_COPY(KPasswordDialog)
340};
341
342Q_DECLARE_OPERATORS_FOR_FLAGS(KPasswordDialog::KPasswordDialogFlags)
343
344#endif
345

source code of kwidgetsaddons/src/kpassworddialog.h