KWidgetsAddons

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

KDE's Doxygen guidelines are available online.