KWidgetsAddons

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

KDE's Doxygen guidelines are available online.