KMessageDialog
#include <KMessageDialog>
Public Types | |
enum | ButtonType { Ok = 1 , Cancel = 2 , PrimaryAction = 3 , SecondaryAction = 4 } |
enum | Type { QuestionTwoActions = 1 , QuestionTwoActionsCancel = 2 , WarningTwoActions = 3 , WarningTwoActionsCancel = 4 , WarningContinueCancel = 5 , Information = 6 , Error = 8 } |
Public Types inherited from QDialog | |
enum | DialogCode |
Public Types inherited from QWidget | |
enum | RenderFlag |
Public Types inherited from QPaintDevice | |
enum | PaintDeviceMetric |
Detailed Description
KMessageDialog creates a message box similar to the ones you get from KMessageBox, but that can be used asynchronously, i.e.
you can show the dialog by using show()
or open()
.
This class contructs a dialog similar to the dialogs the KMessageBox convenience functions create. The main difference is that the KMessageBox methods typically use exec()
to show the dialogs; one of the main disadvantages of using exec()
, is that it starts a nested eventloop, which could lead to nasty crashes.
Another difference is that the API is supposed to be slightly easier to use as it has various methods to set up the dialog, e.g. setCaption(), setDetails() ...etc.
By default, appropriate buttons based on the dialog type are added (since 5.85) (e.g. an "OK" button is added to an Information dialog), you can set custom buttons by using the setButtons() method.
The QDialog::done() slot is called to set the result of the dialog, which will emit the QDialog::finished() signal with that result. The result is one of the KMessageDialog::ButtonType enum. This is useful as you can tell exactly which button was clicked by the user. E.g.:
- the secondary action button having been clicked, in which case you may still want to save the status of the "Do not ask again" CheckBox
- the "Cancel" button having been clicked, in which case you ideally will ignore the status of the "Do not ask again" CheckBox
For "warning" dialogs, i.e. dialogs with a potentially destructive action, the default button is set to a button with the QDialogButtonBox::RejectRole. If the "Cancel" button
* is used, it will be the default, otherwise the secondary action button.
This class intends to be very flexible with the buttons that can be used, since you can call the setButtons() method with a KGuiItem that has custom text/icon.
Since Frameworks 5.97 a notification sound is played when the dialog opens like KMessageBox does, this can be controlled using the setNotifyEnabled() method.
Example:
QStringLiteral("Back or forward?"),nullptr);dlg->setCaption(QStringLiteral("Window Title"));dlg->setDetails(QStringLiteral("Some more details."));dlg->setDontAskAgainText(QStringLiteral("Do not ask again"));dlg->setDontAskAgainChecked(false);// Delete the dialog when it's closeddlg->setAttribute(Qt::WA_DeleteOnClose);// Make the dialog window modaldlg->setWindowModality(Qt::WindowModal);switch(button) {// The user clicked the primary action, handle the result...// save the "do not ask again" box status...break;// The user clicked the secondary action, handle the result...// save the "do not ask again" box status...break;case KMessageDialog::Cancel:// The user clicked cancel, reject the changes...break;default:break;}});dlg->show();@ QuestionTwoActionsCancelQuestion dialog with two buttons and Cancel;.Definition kmessagedialog.h:124KMessageDialog(KMessageDialog::Type type, const QString &text, QWidget *parent=nullptr)Constructs a KMessageDialog.Definition kmessagedialog.cpp:64KGuiItem back(BidiMode useBidi)Returns the 'Back' gui item, like Konqueror's back button.Definition kstandardguiitem.cpp:255KGuiItem forward(BidiMode useBidi)Returns the 'Forward' gui item, like Konqueror's forward button.Definition kstandardguiitem.cpp:261void finished(int result)int result() const constQMetaObject::Connection connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)T qobject_cast(QObject *object)WA_DeleteOnCloseWindowModal- Since
- 5.77
Definition at line 106 of file kmessagedialog.h.
Member Enumeration Documentation
◆ ButtonType
Button types.
- Since
- 5.100
Enumerator | |
---|---|
Ok | Ok button. |
Cancel | Cancel button. |
PrimaryAction | Primary action button. |
SecondaryAction | Secondary action button. |
Definition at line 115 of file kmessagedialog.h.
◆ Type
Definition at line 122 of file kmessagedialog.h.
Constructor & Destructor Documentation
◆ KMessageDialog() [1/2]
|
explicit |
Constructs a KMessageDialog.
Buttons based on the dialog type are set by default in some cases, using KStandardGuiItem instances. For the dialog types Information and Error the button is set to KStandardGuiItem::ok(). For the type WarningContinueCancel the buttons are set to KStandardGuiItem::cont() & KStandardGuiItem::cancel().
For the other Quesion* and Warning* types the buttons are to be set explicitly.
- Parameters
-
type the dialog Type, one of KMessageDialog::Type enum text the text message that is going to be displayed in the dialog parent a QWidget* that will be set as the dialog parent
Definition at line 64 of file kmessagedialog.cpp.
◆ KMessageDialog() [2/2]
|
explicit |
This constructor takes the window Id of the parent window, instead of a QWidget*.
- Parameters
-
type the dialog Type, one of KMessageDialog::Type enum text the text message that is going to be displayed in the dialog parent_id the native parent's window system identifier
Definition at line 199 of file kmessagedialog.cpp.
◆ ~KMessageDialog()
|
override |
Destructor.
Definition at line 209 of file kmessagedialog.cpp.
Member Function Documentation
◆ beep()
|
static |
Manually play the notification sound.
When implementing your entirely own message box, not using KMessageDialog, you can call this function to play the relevant notification sound (if enabled).
- Note
- You don't need to call this when using KMessageDialog, it plays the sound automatically.
- Parameters
-
type The message box type text The message box contents, for accessibility purposes. dialog The dialog that was displayed
- Since
- 6.0
- See also
- setNotifyEnabled
Definition at line 474 of file kmessagedialog.cpp.
◆ isDontAskAgainChecked()
bool KMessageDialog::isDontAskAgainChecked | ( | ) | const |
This can be used to query the status of the "Do not ask again" checkbox; returns true
if the box is checked and false
otherwise.
- Note
- This method will return
false
if a checkbox widget isn't shown in the dialog. The dialog will not show a checkbox if setDontAskAgainText() was not used previously to add a checkbox to begin with.
Definition at line 436 of file kmessagedialog.cpp.
◆ isNotifyEnabled()
bool KMessageDialog::isNotifyEnabled | ( | ) | const |
Whether a KNotification is emitted when the dialog is shown.
This typically plays a notification sound. Default is true.
- Since
- 5.97
- See also
- KMessageBox::Notify
Definition at line 455 of file kmessagedialog.cpp.
◆ setButtons()
void KMessageDialog::setButtons | ( | const KGuiItem & | primaryAction = KGuiItem(), |
const KGuiItem & | secondaryAction = KGuiItem(), | ||
const KGuiItem & | cancelAction = KGuiItem() ) |
Sets the buttons in the buttom box.
Using this method, you can customize the behavior based on your use-case, by using a KGuiItem to get a button with custom text and icon.
Since 5.85 buttons based on the dialog type are added by default (see KMessageDialog(KMessageDialog::Type, const QString &, QWidget *) for details). Before, this method had to be called explicitly to have any buttons added to the dialog.
- Note
- For dialog types Information and Error only one button (KStandardGuiItem::ok()) is added to the dialog.
- Parameters
-
primaryAction the action for the primary button. Reported in the result for dialog types Information and Error as KMessageDialog::Ok enum value, otherwise as KMessageDialog::PrimaryAction. secondaryAction the action for the secondary button. Reported in the result as KMessageDialog::SecondaryAction enum value. Ignored with all dialog types without a "secondary" action. cancelAction the action for the cancel button. Reported in the result as KMessageDialog::Cancel enum value. Ignored with all dialog types without a Cancel button.
Definition at line 337 of file kmessagedialog.cpp.
◆ setCaption()
This can be used to set the title of the dialog window.
If you pass an empty QString(), a generic title will be used depending on the dialog Type. E.g. for KMessageDialog::WarningTwoActions, "Warning" will be used.
Definition at line 214 of file kmessagedialog.cpp.
◆ setDetails()
This will add a KCollapsibleGroupBox with a title "Details", as the class name implies it is collapsible (and collapsed by default); you can use it to add a more detailed explanation of what the dialog is trying to tell the user.
If details
is empty, the details widget will not be shown.
Definition at line 318 of file kmessagedialog.cpp.
◆ setDontAskAgainChecked()
void KMessageDialog::setDontAskAgainChecked | ( | bool | isChecked | ) |
This can be used to set the initial status of the "Do not ask again" checkbox, checked or unchecked, by setting isChecked
to true
or false
respectively.
You need to call setDontAskAgainText() first to actually show a checkbox in the dialog, otherwise calling this function will have no effect.
Definition at line 424 of file kmessagedialog.cpp.
◆ setDontAskAgainText()
This will add a "Do not ask again" checkbox to the dialog with the text from dontAskAgainText
.
You can set the initial status of the checkbox by using setDontAskAgainChecked().
If dontAskAgainText
is empty, no checkbox will be shown.
Typical usage of this checkbox is for recurring questions, e.g. showing a dialog to confirm moving files/directories to trash, the user can then set the checkbox so as not to be asked about that again.
You can get the state of the checkbox by using isDontAskAgainChecked().
Definition at line 418 of file kmessagedialog.cpp.
◆ setIcon()
This can be used to set an icon that will be shown next to the main text message.
If you pass a null QIcon() a generic icon based on the dialog Type will be used. E.g. for KMessageDialog::QuestionTwoActions, QMessageBox::Question will be used.
Definition at line 246 of file kmessagedialog.cpp.
◆ setListWidgetItems()
void KMessageDialog::setListWidgetItems | ( | const QStringList & | strlist | ) |
This will add a QListWidget to the dialog and populate it with strlist
.
If strlist
is empty, the list widget will not be shown.
Definition at line 287 of file kmessagedialog.cpp.
◆ setNotifyEnabled()
void KMessageDialog::setNotifyEnabled | ( | bool | enable | ) |
Whether to emit a KNotification when the dialog is shown.
This typically plays a notification sound.
- Since
- 5.97
- See also
- KMessageBox::Notify
Definition at line 460 of file kmessagedialog.cpp.
◆ setOpenExternalLinks()
void KMessageDialog::setOpenExternalLinks | ( | bool | isAllowed | ) |
Sets the text labels in the dialog to either allow opening external links or not.
Definition at line 448 of file kmessagedialog.cpp.
◆ showEvent()
|
overrideprotectedvirtual |
Reimplemented from QDialog.
Definition at line 465 of file kmessagedialog.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.