File indexing completed on 2024-04-28 03:59:07
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 1999 Waldo Bastian <bastian@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-only 0006 */ 0007 0008 // krazy:excludeall=dpointer 0009 0010 #ifndef KMESSAGEBOX_H 0011 #define KMESSAGEBOX_H 0012 0013 #include <QDialogButtonBox> 0014 #include <QMessageBox> 0015 #include <QStringList> 0016 0017 #include <kguiitem.h> 0018 #include <kstandardguiitem.h> 0019 0020 #include <kwidgetsaddons_export.h> 0021 0022 class KMessageBoxDontAskAgainInterface; 0023 class KMessageBoxNotifyInterface; 0024 class QDialog; 0025 class QDialogButtonBox; 0026 class QWidget; 0027 class KConfig; 0028 0029 /** 0030 * Easy message dialog box. 0031 * 0032 * Provides convenience functions for some i18n'ed standard dialogs, 0033 * as well as audible notification via @ref KNotification 0034 * 0035 * The text in message boxes is wrapped automatically. The text may either 0036 * be plaintext or richtext. If the text is plaintext, a newline-character 0037 * may be used to indicate the end of a paragraph. 0038 * 0039 * \image html kmessagebox.png "An information dialog box" 0040 * 0041 * @author Waldo Bastian (bastian@kde.org) 0042 */ 0043 namespace KMessageBox 0044 { 0045 /** 0046 * Button types. 0047 */ 0048 enum ButtonCode { 0049 Ok = 1, ///< Ok button 0050 Cancel = 2, ///< Cancel button 0051 PrimaryAction = 3, ///< Primary action button; @since 5.100 0052 SecondaryAction = 4, ///< Secondary action button; @since 5.100 0053 Continue = 5, ///< Continue button 0054 }; 0055 0056 enum DialogType { 0057 QuestionTwoActions = 1, ///< Question dialog with two buttons; @since 5.100 0058 WarningTwoActions = 2, ///< Warning dialog with two buttons; @since 5.100 0059 WarningContinueCancel = 3, ///< Warning dialog with Continue and Cancel 0060 WarningTwoActionsCancel = 4, ///< Warning dialog with two buttons and Cancel; @since 5.100 0061 Information = 5, ///< Information dialog 0062 // Reserved for: SSLMessageBox = 6 0063 Error = 8, ///< Error dialog 0064 QuestionTwoActionsCancel = 9, ///< Question dialog with two buttons and Cancel; @since 5.100 0065 }; 0066 0067 /** 0068 * @see Options 0069 */ 0070 enum Option { 0071 Notify = 1, ///< Emit a KNotify event 0072 AllowLink = 2, ///< The message may contain links. 0073 Dangerous = 4, ///< The action to be confirmed by the dialog is a potentially destructive one. The default button will be set to Cancel or SecondaryAction, 0074 ///< depending on which is available. 0075 NoExec = 16, ///< Do not call exec() in createKMessageBox() 0076 WindowModal = 32, ///< The window is to be modal relative to its parent. By default, it is application modal. 0077 }; 0078 0079 /** 0080 * Stores a combination of #Option values. 0081 */ 0082 Q_DECLARE_FLAGS(Options, Option) 0083 0084 // This declaration must be defined before first Option is used in method signatures 0085 Q_DECLARE_OPERATORS_FOR_FLAGS(Options) 0086 0087 /** 0088 * Display a "question" dialog with two action buttons. 0089 * 0090 * To be used for questions like "Do you want to save the message for later or discard it?". 0091 * 0092 * The default button is the primary button. Pressing "Esc" triggers the secondary button. 0093 * 0094 * @param parent the parent widget 0095 * @param text the message string 0096 * @param title the message box title. If an empty string, defaults to i18n("Question"). 0097 * @param primaryAction the action for the primary button 0098 * @param secondaryAction the action for the secondary button 0099 * @param dontAskAgainName If not an empty string, a checkbox is added with which 0100 * further confirmation can be turned off. 0101 * The string is used to lookup and store the setting 0102 * in the applications config file. 0103 * The setting is stored in the "Notification Messages" group. 0104 * If @p dontAskAgainName starts with a ':' then the setting 0105 * is stored in the global config file. 0106 * @param options see Option 0107 * 0108 * @returns @c PrimaryAction if the primary button is triggered, @c SecondaryAction 0109 * if the secondary button is triggered. 0110 * 0111 * @since 5.100 0112 */ 0113 KWIDGETSADDONS_EXPORT 0114 ButtonCode questionTwoActions(QWidget *parent, 0115 const QString &text, 0116 const QString &title, 0117 const KGuiItem &primaryAction, 0118 const KGuiItem &secondaryAction, 0119 const QString &dontAskAgainName = QString(), 0120 Options options = Notify); 0121 0122 /** 0123 * Display a "question" dialog with two action buttons and a cancel button. 0124 * 0125 * To be used for questions like "Do you want to save the message for later or discard it?". 0126 * 0127 * The default button is the primary button. Pressing "Esc" triggers the cancel button. 0128 * 0129 * @param parent the parent widget 0130 * @param text the message string 0131 * @param title the message box title. If an empty string, defaults to i18n("Question"). 0132 * @param primaryAction the action for the primary button 0133 * @param secondaryAction the action for the secondary button 0134 * @param cancelAction the action for the cancel button 0135 * @param dontAskAgainName If not an empty string, a checkbox is added with which 0136 * further confirmation can be turned off. 0137 * The string is used to lookup and store the setting 0138 * in the applications config file. 0139 * The setting is stored in the "Notification Messages" group. 0140 * If @p dontAskAgainName starts with a ':' then the setting 0141 * is stored in the global config file. 0142 * @param options see Option 0143 * 0144 * @returns @c PrimaryAction if the primary button is triggered, @c SecondaryAction 0145 * if the secondary button is triggered. @c Cancel if the cancel button is triggered. 0146 * 0147 * @since 5.100 0148 */ 0149 KWIDGETSADDONS_EXPORT 0150 ButtonCode questionTwoActionsCancel(QWidget *parent, 0151 const QString &text, 0152 const QString &title, 0153 const KGuiItem &primaryAction, 0154 const KGuiItem &secondaryAction, 0155 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 0156 const QString &dontAskAgainName = QString(), 0157 Options options = Notify); 0158 0159 /** 0160 * Display a "question" dialog with a listbox to show information to the user 0161 * and two action buttons. 0162 * 0163 * To be used for questions like "Do you really want to delete these files?" 0164 * and show the user exactly which files are going to be deleted in case. 0165 * 0166 * The default button is the primary button. Pressing "Esc" triggers the secondary button. 0167 * 0168 * @param parent the parent widget 0169 * @param text the message string 0170 * @param strlist List of strings to be written in the listbox. If the list is 0171 * empty, it doesn't show any listbox, working as questionTwoActions(). 0172 * @param title the message box title. If an empty string, defaults to i18n("Question"). 0173 * @param primaryAction the action for the primary button 0174 * @param secondaryAction the action for the secondary button 0175 * @param dontAskAgainName If not an empty string, a checkbox is added with which 0176 * further confirmation can be turned off. 0177 * The string is used to lookup and store the setting 0178 * in the applications config file. 0179 * The setting is stored in the "Notification Messages" group. 0180 * If @p dontAskAgainName starts with a ':' then the setting 0181 * is stored in the global config file. 0182 * @param options see Option 0183 * 0184 * @returns @c PrimaryAction if the primary button is triggered, @c SecondaryAction 0185 * if the secondary button is triggered. 0186 * 0187 * @since 5.100 0188 */ 0189 KWIDGETSADDONS_EXPORT 0190 ButtonCode questionTwoActionsList(QWidget *parent, 0191 const QString &text, 0192 const QStringList &strlist, 0193 const QString &title, 0194 const KGuiItem &primaryAction, 0195 const KGuiItem &secondaryAction, 0196 const QString &dontAskAgainName = QString(), 0197 Options options = Notify); 0198 0199 /** 0200 * Display a "warning" dialog with two action buttons. 0201 * 0202 * To be used for questions like "Shall I update your configuration?". 0203 * The text should explain the implication of both actions. 0204 * 0205 * The default button is the secondary button. Pressing "Esc" triggers the secondary button. 0206 * 0207 * @param parent the parent widget 0208 * @param text the message string 0209 * @param title the message box title. If an empty string, defaults to i18n("Warning"). 0210 * @param primaryAction the action for the primary button 0211 * @param secondaryAction the action for the secondary button 0212 * @param dontAskAgainName If not an empty string, a checkbox is added with which 0213 * further confirmation can be turned off. 0214 * The string is used to lookup and store the setting 0215 * in the applications config file. 0216 * The setting is stored in the "Notification Messages" group. 0217 * If @p dontAskAgainName starts with a ':' then the setting 0218 * is stored in the global config file. 0219 * @param options see Options 0220 * 0221 * @returns @c PrimaryAction if the primary button is triggered, @c SecondaryAction 0222 * if the secondary button is triggered. 0223 * 0224 * @since 5.100 0225 */ 0226 KWIDGETSADDONS_EXPORT 0227 ButtonCode warningTwoActions(QWidget *parent, 0228 const QString &text, 0229 const QString &title, 0230 const KGuiItem &primaryAction, 0231 const KGuiItem &secondaryAction, 0232 const QString &dontAskAgainName = QString(), 0233 Options options = Options(Notify | Dangerous)); 0234 0235 /** 0236 * Display a "warning" dialog with a listbox to show information to the user 0237 * and two action buttons. 0238 * 0239 * To be used for questions like "Shall I update your configuration?". 0240 * The text should explain the implication of both actions. 0241 * 0242 * The default button is the secondary button. Pressing "Esc" triggers the secondary button. 0243 * 0244 * @param parent the parent widget 0245 * @param text the message string 0246 * @param strlist List of strings to be written in the listbox. If the list is 0247 * empty, it doesn't show any listbox, working as warningTwoActions. 0248 * @param title the message box title. If an empty string, defaults to i18n("Warning"). 0249 * @param primaryAction the action for the primary button 0250 * @param secondaryAction the action for the secondary button 0251 * @param dontAskAgainName If not an empty string, a checkbox is added with which 0252 * further confirmation can be turned off. 0253 * The string is used to lookup and store the setting 0254 * in the applications config file. 0255 * The setting is stored in the "Notification Messages" group. 0256 * If @p dontAskAgainName starts with a ':' then the setting 0257 * is stored in the global config file. 0258 * @param options see Options 0259 * 0260 * @returns @c PrimaryAction if the primary button is triggered, @c SecondaryAction 0261 * if the secondary button is triggered. 0262 * 0263 * @since 5.100 0264 */ 0265 KWIDGETSADDONS_EXPORT 0266 ButtonCode warningTwoActionsList(QWidget *parent, 0267 const QString &text, 0268 const QStringList &strlist, 0269 const QString &title, 0270 const KGuiItem &primaryAction, 0271 const KGuiItem &secondaryAction, 0272 const QString &dontAskAgainName = QString(), 0273 Options options = Options(Notify | Dangerous)); 0274 0275 /** 0276 * Display a "warning" dialog. 0277 * 0278 * @param parent Parent widget. 0279 * @param text Message string. 0280 * @param title Message box title. The application name is added to 0281 * the title. The default title is i18n("Warning"). 0282 * @param buttonContinue The text for the first button. 0283 * The default is KStandardGuiItem::cont(). 0284 * @param buttonCancel The text for the second button. 0285 * The default is KStandardGuiItem::cancel(). 0286 * @param dontAskAgainName If provided, a checkbox is added with which 0287 * further confirmation can be turned off. 0288 * The string is used to lookup and store the setting 0289 * in the applications config file. 0290 * The setting is stored in the "Notification Messages" group. 0291 * If @p dontAskAgainName starts with a ':' then the setting 0292 * is stored in the global config file. 0293 * @param options see Options 0294 * 0295 * @return @p Continue is returned if the Continue-button is pressed. 0296 * @p Cancel is returned if the Cancel-button is pressed. 0297 * 0298 * To be used for questions like "You are about to Print. Are you sure?" 0299 * the continueButton should then be labeled "Print". 0300 * 0301 * The default button is buttonContinue. Pressing "Esc" selects "Cancel". 0302 */ 0303 KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancel(QWidget *parent, 0304 const QString &text, 0305 const QString &title = QString(), 0306 const KGuiItem &buttonContinue = KStandardGuiItem::cont(), 0307 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(), 0308 const QString &dontAskAgainName = QString(), 0309 Options options = Notify); 0310 0311 /** 0312 * Display a "warning" dialog with a collapsible "Details" section. 0313 * 0314 * @since 5.61 0315 */ 0316 KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelDetailed(QWidget *parent, 0317 const QString &text, 0318 const QString &title = QString(), 0319 const KGuiItem &buttonContinue = KStandardGuiItem::cont(), 0320 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(), 0321 const QString &dontAskAgainName = QString(), 0322 Options options = Notify, 0323 const QString &details = QString()); 0324 0325 /** 0326 * Display a "warning" dialog with a listbox to show information to the user. 0327 * 0328 * @param parent Parent widget. 0329 * @param text Message string. 0330 * @param strlist List of strings to be written in the listbox. If the 0331 * list is empty, it doesn't show any listbox, working 0332 * as warningContinueCancel. 0333 * @param title Message box title. The application name is added to 0334 * the title. The default title is i18n("Warning"). 0335 * @param buttonContinue The text for the first button. 0336 * The default is KStandardGuiItem::cont(). 0337 * @param buttonCancel The text for the second button. 0338 * The default is KStandardGuiItem::cancel(). 0339 * @param dontAskAgainName If provided, a checkbox is added with which 0340 * further confirmation can be turned off. 0341 * The string is used to lookup and store the setting 0342 * in the applications config file. 0343 * The setting is stored in the "Notification Messages" group. 0344 * If @p dontAskAgainName starts with a ':' then the setting 0345 * is stored in the global config file. 0346 * 0347 * @param options see Options 0348 * 0349 * @return @p Continue is returned if the Continue-button is pressed. 0350 * @p Cancel is returned if the Cancel-button is pressed. 0351 * 0352 * To be used for questions like "You are about to Print. Are you sure?" 0353 * the continueButton should then be labeled "Print". 0354 * 0355 * The default button is buttonContinue. Pressing "Esc" selects "Cancel". 0356 */ 0357 KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelList(QWidget *parent, 0358 const QString &text, 0359 const QStringList &strlist, 0360 const QString &title = QString(), 0361 const KGuiItem &buttonContinue = KStandardGuiItem::cont(), 0362 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(), 0363 const QString &dontAskAgainName = QString(), 0364 Options options = Notify); 0365 0366 /** 0367 * Display a "warning" dialog with two action buttons and a cancel button. 0368 * 0369 * To be used for questions like "Shall I update your configuration?". 0370 * The text should explain the implication of both actions. 0371 * 0372 * The default button is the cancel button. Pressing "Esc" triggers the cancel button. 0373 * 0374 * @param parent the parent widget 0375 * @param text the message string 0376 * @param title the message box title. If an empty string, defaults to i18n("Warning"). 0377 * @param primaryAction the action for the primary button 0378 * @param secondaryAction the action for the secondary button 0379 * @param cancelAction the action for the cancel button 0380 * @param dontAskAgainName If not an empty string, a checkbox is added with which 0381 * further confirmation can be turned off. 0382 * The string is used to lookup and store the setting 0383 * in the applications config file. 0384 * The setting is stored in the "Notification Messages" group. 0385 * If @p dontAskAgainName starts with a ':' then the setting 0386 * is stored in the global config file. 0387 * @param options see Options 0388 * 0389 * @returns @c PrimaryAction if the primary button is triggered, @c SecondaryAction 0390 * if the secondary button is triggered. @c Cancel if the cancel button is triggered. 0391 * 0392 * @since 5.100 0393 */ 0394 KWIDGETSADDONS_EXPORT 0395 ButtonCode warningTwoActionsCancel(QWidget *parent, 0396 const QString &text, 0397 const QString &title, 0398 const KGuiItem &primaryAction, 0399 const KGuiItem &secondaryAction, 0400 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 0401 const QString &dontAskAgainName = QString(), 0402 Options options = Options(Notify | Dangerous)); 0403 0404 /** 0405 * Display a "warning" dialog with a listbox to show information 0406 * to the user, two action buttons and a cancel button. 0407 * 0408 * To be used for questions like "Shall I update your configuration?". 0409 * The text should explain the implication of both actions. 0410 * 0411 * The default button is the cancel button. Pressing "Esc" triggers the cancel button. 0412 * 0413 * @param parent the parent widget 0414 * @param text the message string 0415 * @param strlist a List of strings to be written in the listbox. If the 0416 * list is empty, it doesn't show any listbox, working 0417 * as warningTwoActionsCancel(). 0418 * @param title the message box title. If an empty string, defaults to i18n("Warning"). 0419 * @param primaryAction the action for the primary button 0420 * @param secondaryAction the action for the secondary button 0421 * @param cancelAction the action for the cancel button 0422 * @param dontAskAgainName If not an empty string, a checkbox is added with which 0423 * further confirmation can be turned off. 0424 * The string is used to lookup and store the setting 0425 * in the applications config file. 0426 * The setting is stored in the "Notification Messages" group. 0427 * If @p dontAskAgainName starts with a ':' then the setting 0428 * is stored in the global config file. 0429 * @param options see Options 0430 * 0431 * @returns @c PrimaryAction if the primary button is triggered, @c SecondaryAction 0432 * if the secondary button is triggered. @c Cancel if the cancel button is triggered. 0433 * 0434 * @since 5.100 0435 */ 0436 KWIDGETSADDONS_EXPORT 0437 ButtonCode warningTwoActionsCancelList(QWidget *parent, 0438 const QString &text, 0439 const QStringList &strlist, 0440 const QString &title, 0441 const KGuiItem &primaryAction, 0442 const KGuiItem &secondaryAction, 0443 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 0444 const QString &dontAskAgainName = QString(), 0445 Options options = Options(Notify | Dangerous)); 0446 0447 /** 0448 * Display an "Error" dialog. 0449 * 0450 * @param parent Parent widget. 0451 * @param text Message string. 0452 * @param title Message box title. The application name is added to 0453 * the title. The default title is i18n("Error"). 0454 * @param options see Options 0455 * 0456 * Your program messed up and now it's time to inform the user. 0457 * To be used for important things like "Sorry, I deleted your hard disk." 0458 * 0459 * The default button is "&OK". Pressing "Esc" selects the OK-button. 0460 * 0461 * @note The OK button will always have the i18n'ed text '&OK'. 0462 */ 0463 KWIDGETSADDONS_EXPORT void error(QWidget *parent, const QString &text, const QString &title = QString(), Options options = Notify); 0464 0465 /** 0466 * Display an "Error" dialog. 0467 * 0468 * @param parent Parent widget. 0469 * @param text Message string. 0470 * @param title Message box title. The application name is added to 0471 * the title. The default title is i18n("Error"). 0472 * @param buttonOk The text for the only button. 0473 * The default is KStandardGuiItem::ok(). 0474 * @param options see Options 0475 * 0476 * There is only one button, therefore it's the default button, and pressing "Esc" selects it as well. 0477 * 0478 * @since 5.97 0479 */ 0480 KWIDGETSADDONS_EXPORT 0481 void error(QWidget *parent, 0482 const QString &text, 0483 const QString &title /*= QString()*/, 0484 const KGuiItem &buttonOk /*= KStandardGuiItem::ok()*/, 0485 Options options = Notify); // TODO KF6 merge with previous overload 0486 0487 /** 0488 * Display an "Error" dialog with a listbox. 0489 * 0490 * @param parent Parent widget. 0491 * @param text Message string. 0492 * @param strlist List of strings to be written in the listbox. If the 0493 * list is empty, it doesn't show any listbox, working 0494 * as error(). 0495 * @param title Message box title. The application name is added to 0496 * the title. The default title is i18n("Error"). 0497 * @param options see Options 0498 * 0499 * Your program messed up and now it's time to inform the user. 0500 * To be used for important things like "Sorry, I deleted your hard disk." 0501 * 0502 * The default button is "&OK". Pressing "Esc" selects the OK-button. 0503 * 0504 * @note The OK button will always have the i18n'ed text '&OK'. 0505 */ 0506 KWIDGETSADDONS_EXPORT void 0507 errorList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title = QString(), Options options = Notify); 0508 0509 /** 0510 * Displays an "Error" dialog with a "Details >>" button. 0511 * 0512 * @param parent Parent widget. 0513 * @param text Message string. 0514 * @param details Detailed message string. 0515 * @param title Message box title. The application name is added to 0516 * the title. The default title is i18n("Error"). 0517 * @param options see Options 0518 * 0519 * Your program messed up and now it's time to inform the user. 0520 * To be used for important things like "Sorry, I deleted your hard disk." 0521 * 0522 * The @p details message can contain additional information about 0523 * the problem and can be shown on request to advanced/interested users. 0524 * 0525 * The default button is "&OK". Pressing "Esc" selects the OK-button. 0526 * 0527 * @note The OK button will always have the i18n'ed text '&OK'. 0528 */ 0529 KWIDGETSADDONS_EXPORT void 0530 detailedError(QWidget *parent, const QString &text, const QString &details, const QString &title = QString(), Options options = Notify); 0531 0532 /** 0533 * Displays an "Error" dialog with a "Details >>" button. 0534 * 0535 * @param parent Parent widget. 0536 * @param text Message string. 0537 * @param details Detailed message string. 0538 * @param title Message box title. The application name is added to 0539 * the title. The default title is i18n("Error"). 0540 * @param buttonOk The text for the only button. 0541 * The default is KStandardGuiItem::ok(). 0542 * @param options see Options 0543 * 0544 * Your program messed up and now it's time to inform the user. 0545 * To be used for important things like "Sorry, I deleted your hard disk." 0546 * 0547 * The @p details message can contain additional information about 0548 * the problem and can be shown on request to advanced/interested users. 0549 * 0550 * There is only one button, therefore it's the default button, and pressing "Esc" selects it as well. 0551 * 0552 * @since 5.97 0553 */ 0554 KWIDGETSADDONS_EXPORT 0555 void detailedError(QWidget *parent, 0556 const QString &text, 0557 const QString &details, 0558 const QString &title /*= QString()*/, 0559 const KGuiItem &buttonOk /*= KStandardGuiItem::ok()*/, 0560 Options options = Notify); // TODO KF6 merge with previous overload 0561 0562 /** 0563 * Display an "Information" dialog. 0564 * 0565 * @param parent Parent widget. 0566 * @param text Message string. 0567 * @param title Message box title. The application name is added to 0568 * the title. The default title is i18n("Information"). 0569 * @param dontShowAgainName If provided, a checkbox is added with which 0570 * further notifications can be turned off. 0571 * The string is used to lookup and store the setting 0572 * in the applications config file. 0573 * The setting is stored in the "Notification Messages" group. 0574 * @param options see Options 0575 * 0576 * 0577 * Your program wants to tell the user something. 0578 * To be used for things like: 0579 * "Your bookmarks have been rearranged." 0580 * 0581 * The default button is "&OK". Pressing "Esc" selects the OK-button. 0582 * 0583 * @note The OK button will always have the i18n'ed text '&OK'. 0584 */ 0585 KWIDGETSADDONS_EXPORT void 0586 information(QWidget *parent, const QString &text, const QString &title = QString(), const QString &dontShowAgainName = QString(), Options options = Notify); 0587 0588 /** 0589 * Display an "Information" dialog with a listbox. 0590 * 0591 * @param parent Parent widget. 0592 * @param text Message string. 0593 * @param strlist List of strings to be written in the listbox. If the 0594 * list is empty, it doesn't show any listbox, working 0595 * as information. 0596 * @param title Message box title. The application name is added to 0597 * the title. The default title is i18n("Information"). 0598 * @param dontShowAgainName If provided, a checkbox is added with which 0599 * further notifications can be turned off. 0600 * The string is used to lookup and store the setting 0601 * in the applications config file. 0602 * The setting is stored in the "Notification Messages" group. 0603 * @param options see Options 0604 * 0605 * 0606 * Your program wants to tell the user something. 0607 * To be used for things like: 0608 * "The following bookmarks have been rearranged:" 0609 * 0610 * The default button is "&OK". Pressing "Esc" selects the OK-button. 0611 * 0612 * @note The OK button will always have the i18n'ed text '&OK'. 0613 */ 0614 KWIDGETSADDONS_EXPORT void informationList(QWidget *parent, 0615 const QString &text, 0616 const QStringList &strlist, 0617 const QString &title = QString(), 0618 const QString &dontShowAgainName = QString(), 0619 Options options = Notify); 0620 0621 /** 0622 * Enable all messages which have been turned off with the 0623 * @p dontShowAgainName feature. 0624 */ 0625 KWIDGETSADDONS_EXPORT void enableAllMessages(); 0626 0627 /** 0628 * Re-enable a specific @p dontShowAgainName messages that had 0629 * previously been turned off. 0630 * @see saveDontShowAgainTwoActions() 0631 * @see saveDontShowAgainContinue() 0632 */ 0633 KWIDGETSADDONS_EXPORT void enableMessage(const QString &dontShowAgainName); 0634 0635 /** 0636 * Alternate method to show a messagebox: 0637 * 0638 * @param parent Parent widget. 0639 * @param type type of message box: QuestionTwoActions, WarningTwoActions, WarningContinueCancel... 0640 * @param text Message string. 0641 * @param title Message box title. 0642 * @param primaryAction The KGuiItem for the first button. 0643 * @param secondaryAction The KGuiItem for the second button. 0644 * @param cancelAction The text for the third button. 0645 * The default is KStandardGuiItem::cancel(). 0646 * @param dontShowAskAgainName If provided, a checkbox is added with which 0647 * further questions/information can be turned off. If turned off 0648 * all questions will be automatically answered with the 0649 * last answer (either PrimaryAction or SecondaryAction), 0650 * if the message box needs an answer. 0651 * The string is used to lookup and store the setting 0652 * in the applications config file. 0653 * @param options see Options 0654 * Note: for ContinueCancel, primaryAction is the continue button and secondaryAction is unused. 0655 * and for Information, none is used. 0656 * @return a button code, as defined in KMessageBox. 0657 */ 0658 KWIDGETSADDONS_EXPORT 0659 ButtonCode messageBox(QWidget *parent, 0660 DialogType type, 0661 const QString &text, 0662 const QString &title, 0663 const KGuiItem &primaryAction, 0664 const KGuiItem &secondaryAction, 0665 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 0666 const QString &dontShowAskAgainName = QString(), 0667 Options options = Notify); 0668 0669 /** 0670 * @param dontShowAgainName the name that identifies the message box. 0671 * If empty, @c true is always returned. 0672 * @param result reference to a variable to be set to the choice (@c PrimaryAction or @c SecondaryAction) 0673 * that was chosen the last time the message box was shown. 0674 * Only meaningful if the message box should not be shown. 0675 * @returns @c true if the corresponding two actions message box should be shown, @c false otherwise. 0676 * 0677 * @since 5.100 0678 */ 0679 KWIDGETSADDONS_EXPORT 0680 bool shouldBeShownTwoActions(const QString &dontShowAgainName, ButtonCode &result); 0681 0682 /** 0683 * @return true if the corresponding continue/cancel message box should be 0684 * shown. 0685 * @param dontShowAgainName the name that identify the message box. If 0686 * empty, true is always returned. 0687 */ 0688 KWIDGETSADDONS_EXPORT bool shouldBeShownContinue(const QString &dontShowAgainName); 0689 0690 /** 0691 * Save the fact that a two actions message box should not be shown again. 0692 * 0693 * @param dontShowAgainName the name that identifies the message box. 0694 * If empty, this method does nothing. 0695 * @param result the value (@c PrimaryAction or @c SecondaryAction) that should be used 0696 * as the result for the message box. 0697 * 0698 * @since 5.100 0699 */ 0700 KWIDGETSADDONS_EXPORT 0701 void saveDontShowAgainTwoActions(const QString &dontShowAgainName, ButtonCode result); 0702 0703 /** 0704 * Save the fact that the continue/cancel message box should not be shown 0705 * again. 0706 * @param dontShowAgainName the name that identify the message box. If 0707 * empty, this method does nothing. 0708 */ 0709 KWIDGETSADDONS_EXPORT void saveDontShowAgainContinue(const QString &dontShowAgainName); 0710 0711 /** 0712 * Use @p cfg for all settings related to the dontShowAgainName feature. 0713 * If @p cfg is 0 (default) KGlobal::config() will be used. 0714 */ 0715 KWIDGETSADDONS_EXPORT void setDontShowAgainConfig(KConfig *cfg); 0716 0717 /** 0718 * Use @p dontAskAgainInterface for all settings related to the dontShowAgain feature. 0719 * This method does not take ownership of @p dontAskAgainInterface. 0720 * 0721 * @since 5.0 0722 */ 0723 KWIDGETSADDONS_EXPORT void setDontShowAgainInterface(KMessageBoxDontAskAgainInterface *dontAskAgainInterface); 0724 0725 /** 0726 * Use @p notifyInterface to send notifications. 0727 * This method does not take ownership of @p notifyInterface. 0728 * 0729 * @since 5.0 0730 */ 0731 KWIDGETSADDONS_EXPORT void setNotifyInterface(KMessageBoxNotifyInterface *notifyInterface); 0732 0733 /** 0734 * Create content and layout of a standard dialog 0735 * 0736 * @param dialog The parent dialog base 0737 * @param buttons a QDialogButtonBox instance. This function will take care of connecting to it. 0738 * @param icon Which predefined icon the message box shall show. 0739 * @param text Message string. 0740 * @param strlist List of strings to be written in the listbox. 0741 * If the list is empty, it doesn't show any listbox 0742 * @param ask The text of the checkbox. If empty none will be shown. 0743 * @param checkboxReturn The result of the checkbox. If it's initially 0744 * true then the checkbox will be checked by default. 0745 * May be a null pointer. Incompatible with NoExec. 0746 * @param options see Options 0747 * @param details Detailed message string. 0748 * @return A QDialogButtonBox::StandardButton button code, not a KMessageBox 0749 * button code, based on the buttonmask given to the constructor of 0750 * the @p dialog (ie. will return QDialogButtonBox::Yes instead of 0751 * KMessageBox::PrimaryAction). Will return QDialogButtonBox::NoButton if the 0752 * message box is queued for display instead of exec()ed immediately 0753 * or if the option NoExec is set. 0754 * @note Unless NoExec is used, 0755 * the @p dialog that is passed in is deleted by this 0756 * function. Do not delete it yourself. 0757 */ 0758 KWIDGETSADDONS_EXPORT QDialogButtonBox::StandardButton createKMessageBox(QDialog *dialog, 0759 QDialogButtonBox *buttons, 0760 QMessageBox::Icon icon, // krazy:exclude=qclasses 0761 const QString &text, 0762 const QStringList &strlist, 0763 const QString &ask, 0764 bool *checkboxReturn, 0765 Options options, 0766 const QString &details = QString()); 0767 0768 /** 0769 * Create content and layout of a standard dialog 0770 * 0771 * @param dialog The parent dialog base 0772 * @param buttons a QDialogButtonBox instance. This function will take care of connecting to it. 0773 * @param icon A QPixmap containing the icon to be displayed in the 0774 * dialog next to the text. 0775 * @param text Message string. 0776 * @param strlist List of strings to be written in the listbox. 0777 * If the list is empty, it doesn't show any listbox 0778 * @param ask The text of the checkbox. If empty none will be shown. 0779 * @param checkboxReturn The result of the checkbox. If it's initially 0780 * true then the checkbox will be checked by default. 0781 * May be a null pointer. Incompatible with NoExec. 0782 * @param options see Options 0783 * @param details Detailed message string. 0784 * @param notifyType The type of notification to send when this message 0785 * is presentend. 0786 * @return A QDialogButtonBox::StandardButton button code, not a KMessageBox 0787 * button code, based on the buttonmask given to the constructor of 0788 * the @p dialog (ie. will return QDialogButtonBox::Yes instead of 0789 * KMessageBox::PrimaryAction). Will return QDialogButtonBox::NoButton if the 0790 * message box is queued for display instead of exec()ed immediately 0791 * or if the option NoExec is set. 0792 * @note Unless NoExec is used, 0793 * the @p dialog that is passed in is deleted by this 0794 * function. Do not delete it yourself. 0795 */ 0796 KWIDGETSADDONS_EXPORT QDialogButtonBox::StandardButton createKMessageBox(QDialog *dialog, 0797 QDialogButtonBox *buttons, 0798 const QIcon &icon, 0799 const QString &text, 0800 const QStringList &strlist, 0801 const QString &ask, 0802 bool *checkboxReturn, 0803 Options options, 0804 const QString &details = QString(), 0805 QMessageBox::Icon notifyType = QMessageBox::Information); // krazy:exclude=qclasses 0806 0807 /** 0808 * This function accepts the window id of the parent window, instead 0809 * of QWidget*. It should be used only when necessary. 0810 * 0811 * @see questionTwoActions() 0812 * @since 5.100 0813 */ 0814 KWIDGETSADDONS_EXPORT 0815 ButtonCode questionTwoActionsWId(WId parent_id, 0816 const QString &text, 0817 const QString &title, 0818 const KGuiItem &primaryAction, 0819 const KGuiItem &secondaryAction, 0820 const QString &dontAskAgainName = QString(), 0821 Options options = Notify); 0822 0823 /** 0824 * This function accepts the window id of the parent window, instead 0825 * of QWidget*. It should be used only when necessary. 0826 * 0827 * @see questionTwoActionsCancel() 0828 * @since 5.100 0829 */ 0830 KWIDGETSADDONS_EXPORT 0831 ButtonCode questionTwoActionsCancelWId(WId parent_id, 0832 const QString &text, 0833 const QString &title, 0834 const KGuiItem &primaryAction, 0835 const KGuiItem &secondaryAction, 0836 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 0837 const QString &dontAskAgainName = QString(), 0838 Options options = Notify); 0839 0840 /** 0841 * This function accepts the window id of the parent window, instead 0842 * of QWidget*. It should be used only when necessary. 0843 * 0844 * @see questionTwoActionsList() 0845 * @since 5.100 0846 */ 0847 KWIDGETSADDONS_EXPORT 0848 ButtonCode questionTwoActionsListWId(WId parent_id, 0849 const QString &text, 0850 const QStringList &strlist, 0851 const QString &title, 0852 const KGuiItem &primaryAction, 0853 const KGuiItem &secondaryAction, 0854 const QString &dontAskAgainName = QString(), 0855 Options options = Notify); 0856 0857 /** 0858 * This function accepts the window id of the parent window, instead 0859 * of QWidget*. It should be used only when necessary. 0860 * 0861 * @see warningTwoActions() 0862 * @since 5.100 0863 */ 0864 KWIDGETSADDONS_EXPORT 0865 ButtonCode warningTwoActionsWId(WId parent_id, 0866 const QString &text, 0867 const QString &title, 0868 const KGuiItem &primaryAction, 0869 const KGuiItem &secondaryAction, 0870 const QString &dontAskAgainName = QString(), 0871 Options options = Options(Notify | Dangerous)); 0872 0873 /** 0874 * This function accepts the window id of the parent window, instead 0875 * of QWidget*. It should be used only when necessary. 0876 * 0877 * @see warningTwoActionsList() 0878 * @since 5.100 0879 */ 0880 KWIDGETSADDONS_EXPORT 0881 ButtonCode warningTwoActionsListWId(WId parent_id, 0882 const QString &text, 0883 const QStringList &strlist, 0884 const QString &title, 0885 const KGuiItem &primaryAction, 0886 const KGuiItem &secondaryAction, 0887 const QString &dontAskAgainName = QString(), 0888 Options options = Options(Notify | Dangerous)); 0889 0890 /** 0891 * This function accepts the window id of the parent window, instead 0892 * of QWidget*. It should be used only when necessary. 0893 */ 0894 KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelWId(WId parent_id, 0895 const QString &text, 0896 const QString &title = QString(), 0897 const KGuiItem &buttonContinue = KStandardGuiItem::cont(), 0898 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(), 0899 const QString &dontAskAgainName = QString(), 0900 Options options = Notify); 0901 0902 /** 0903 * This function accepts the window id of the parent window, instead 0904 * of QWidget*. It should be used only when necessary. 0905 */ 0906 KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelListWId(WId parent_id, 0907 const QString &text, 0908 const QStringList &strlist, 0909 const QString &title = QString(), 0910 const KGuiItem &buttonContinue = KStandardGuiItem::cont(), 0911 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(), 0912 const QString &dontAskAgainName = QString(), 0913 Options options = Notify); 0914 0915 /** 0916 * This function accepts the window id of the parent window, instead 0917 * of QWidget*. It should be used only when necessary. 0918 * 0919 * @see warningTwoActionsCancel() 0920 * @since 5.100 0921 */ 0922 KWIDGETSADDONS_EXPORT 0923 ButtonCode warningTwoActionsCancelWId(WId parent_id, 0924 const QString &text, 0925 const QString &title, 0926 const KGuiItem &primaryAction, 0927 const KGuiItem &secondaryAction, 0928 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 0929 const QString &dontAskAgainName = QString(), 0930 Options options = Options(Notify | Dangerous)); 0931 0932 /** 0933 * This function accepts the window id of the parent window, instead 0934 * of QWidget*. It should be used only when necessary. 0935 * 0936 * @see warningTwoActionsCancelList() 0937 * @since 5.100 0938 */ 0939 KWIDGETSADDONS_EXPORT 0940 ButtonCode warningTwoActionsCancelListWId(WId parent_id, 0941 const QString &text, 0942 const QStringList &strlist, 0943 const QString &title, 0944 const KGuiItem &primaryAction, 0945 const KGuiItem &secondaryAction, 0946 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 0947 const QString &dontAskAgainName = QString(), 0948 Options options = Options(Notify | Dangerous)); 0949 0950 /** 0951 * This function accepts the window id of the parent window, instead 0952 * of QWidget*. It should be used only when necessary. 0953 */ 0954 KWIDGETSADDONS_EXPORT void errorWId(WId parent_id, const QString &text, const QString &title = QString(), Options options = Notify); 0955 0956 /** 0957 * This function accepts the window id of the parent window, instead 0958 * of QWidget*. It should be used only when necessary. 0959 */ 0960 KWIDGETSADDONS_EXPORT void 0961 errorListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title = QString(), Options options = Notify); 0962 0963 /** 0964 * This function accepts the window id of the parent window, instead 0965 * of QWidget*. It should be used only when necessary. 0966 */ 0967 KWIDGETSADDONS_EXPORT void 0968 detailedErrorWId(WId parent_id, const QString &text, const QString &details, const QString &title = QString(), Options options = Notify); 0969 0970 /** 0971 * This function accepts the window id of the parent window, instead 0972 * of QWidget*. It should be used only when necessary. 0973 * @since 5.97 0974 */ 0975 KWIDGETSADDONS_EXPORT 0976 void detailedErrorWId(WId parent_id, 0977 const QString &text, 0978 const QString &details, 0979 const QString &title /*= QString()*/, 0980 const KGuiItem &buttonOk /*= KStandardGuiItem::ok()*/, 0981 Options options = Notify); // TODO KF6 merge with previous overload 0982 0983 /** 0984 * This function accepts the window id of the parent window, instead 0985 * of QWidget*. It should be used only when necessary. 0986 */ 0987 KWIDGETSADDONS_EXPORT void 0988 informationWId(WId parent_id, const QString &text, const QString &title = QString(), const QString &dontShowAgainName = QString(), Options options = Notify); 0989 0990 /** 0991 * This function accepts the window id of the parent window, instead 0992 * of QWidget*. It should be used only when necessary. 0993 */ 0994 KWIDGETSADDONS_EXPORT void informationListWId(WId parent_id, 0995 const QString &text, 0996 const QStringList &strlist, 0997 const QString &title = QString(), 0998 const QString &dontShowAgainName = QString(), 0999 Options options = Notify); 1000 1001 /** 1002 * This function accepts the window id of the parent window, instead 1003 * of QWidget*. It should be used only when necessary. 1004 */ 1005 KWIDGETSADDONS_EXPORT 1006 ButtonCode messageBoxWId(WId parent_id, 1007 DialogType type, 1008 const QString &text, 1009 const QString &title, 1010 const KGuiItem &primaryAction, 1011 const KGuiItem &secondaryAction, 1012 const KGuiItem &cancelAction = KStandardGuiItem::cancel(), 1013 const QString &dontShowAskAgainName = QString(), 1014 Options options = Notify); 1015 } 1016 1017 #endif