KMessageDialog Class

auto *dlg = new KMessageDialog(KMessageDialog::QuestionTwoActionsCancel,
                               QStringLiteral("Back or forward?"),
                               nullptr);

dlg->setCaption(QStringLiteral("Window Title"));
dlg->setButtons(KStandardGuiItem::back(), KStandardGuiItem::forward(), KStandardGuiItem::cancel());
dlg->setListWidgetItems(QStringList{QStringLiteral("file1"), QStringLiteral("file2")});
dlg->setDetails(QStringLiteral("Some more details."));
dlg->setDontAskAgainText(QStringLiteral("Do not ask again"));
dlg->setDontAskAgainChecked(false);

 // Delete the dialog when it's closed
 dlg->setAttribute(Qt::WA_DeleteOnClose);
 // Make the dialog window modal
 dlg->setWindowModality(Qt::WindowModal);

 QObject::connect(dlg, &QDialog::finished, &app, [dlg](int result) {
     auto button = static_cast<KMessageDialog::ButtonType>(result);
     switch(button) {
     case KMessageDialog::PrimaryAction:
         // The user clicked the primary action, handle the result...
         // save the "do not ask again" box status...
         break;
     case KMessageDialog::SecondaryAction:
         // 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();

Member Function Documentation

[explicit] KMessageDialog::KMessageDialog(KMessageDialog::Type type, const QString &text, QWidget *parent = nullptr)

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.

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

[explicit] KMessageDialog::KMessageDialog(KMessageDialog::Type type, const QString &text, WId parent_id)

This constructor takes the window Id of the parent window, instead of a QWidget*.

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

[override virtual noexcept] KMessageDialog::~KMessageDialog()

Destructor

[static, since 6.0] void KMessageDialog::beep(KMessageDialog::Type type, const QString &text = QString(), QWidget *dialog = nullptr)

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).

type The message box type

text The message box contents, for accessibility purposes.

dialog The dialog that was displayed

This function was introduced in 6.0.

See also setNotifyEnabled.

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.

[since 5.97] bool KMessageDialog::isNotifyEnabled() const

Whether a KNotification is emitted when the dialog is shown.

This typically plays a notification sound. Default is true.

This function was introduced in 5.97.

See also KMessageBox::Notify.

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.

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.

void KMessageDialog::setCaption(const QString &caption)

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.

void KMessageDialog::setDetails(const QString &details)

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.

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.

See also isDontAskAgainChecked().

void KMessageDialog::setDontAskAgainText(const QString &dontAskAgainText)

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().

void KMessageDialog::setIcon(const QIcon &icon)

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.

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.

[since 5.97] void KMessageDialog::setNotifyEnabled(bool enable)

Whether to emit a KNotification when the dialog is shown.

This typically plays a notification sound.

This function was introduced in 5.97.

See also isNotifyEnabled() and KMessageBox::Notify.

void KMessageDialog::setOpenExternalLinks(bool isAllowed)

Sets the text labels in the dialog to either allow opening external links or not.