1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Waldo Bastian <bastian@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-only
6*/
7
8// krazy:excludeall=dpointer
9
10#ifndef KMESSAGEBOX_H
11#define KMESSAGEBOX_H
12
13#include <QDialogButtonBox>
14#include <QMessageBox>
15#include <QStringList>
16
17#include <kguiitem.h>
18#include <kstandardguiitem.h>
19
20#include <kwidgetsaddons_export.h>
21
22class KMessageBoxDontAskAgainInterface;
23class KMessageBoxNotifyInterface;
24class QDialog;
25class QDialogButtonBox;
26class QWidget;
27class KConfig;
28
29/*!
30 * \namespace KMessageBox
31 * \inmodule KWidgetsAddons
32 *
33 * \brief Easy message dialog box.
34 *
35 * Provides convenience functions for some i18n'ed standard dialogs,
36 * as well as audible notification via KNotification
37 *
38 * The text in message boxes is wrapped automatically. The text may either
39 * be plaintext or richtext. If the text is plaintext, a newline-character
40 * may be used to indicate the end of a paragraph.
41 *
42 * \image kmessagebox.png "An information dialog box"
43 */
44namespace KMessageBox
45{
46/*!
47 * Button types.
48 *
49 * \value Ok Ok button
50 * \value Cancel Cancel button
51 * \value[since 5.100] PrimaryAction Primary action button
52 * \value[since 5.100] SecondaryAction Secondary action button
53 * \value Continue Continue button
54 */
55enum ButtonCode {
56 Ok = 1,
57 Cancel = 2,
58 PrimaryAction = 3,
59 SecondaryAction = 4,
60 Continue = 5,
61};
62
63/*!
64 *
65 * \value[since 5.100] QuestionTwoActions Question dialog with two buttons
66 * \value[since 5.100] WarningTwoActions Warning dialog with two buttons
67 * \value WarningContinueCancel Warning dialog with Continue and Cancel
68 * \value[since 5.100] WarningTwoActionsCancel Warning dialog with two buttons and Cancel
69 * \value Information Information dialog
70 * \value Error Error dialog
71 * \value[since 5.100] QuestionTwoActionsCancel Question dialog with two buttons and Cancel
72 */
73enum DialogType {
74 QuestionTwoActions = 1,
75 WarningTwoActions = 2,
76 WarningContinueCancel = 3,
77 WarningTwoActionsCancel = 4,
78 Information = 5,
79 // Reserved for: SSLMessageBox = 6
80 Error = 8,
81 QuestionTwoActionsCancel = 9,
82};
83
84/*!
85 * \value Notify Emit a KNotify event
86 * \value AllowLink The message may contain links.
87 * \value Dangerous The action to be confirmed by the dialog is a potentially destructive one. The default button will be set to Cancel or SecondaryAction,
88 * depending on which is available.
89 * \value NoExec Do not call exec() in createKMessageBox()
90 * \value WindowModal The window is to be modal relative to its parent. By default, it is application modal.
91 * \value[since 6.9] PlainText The label content should be considered as plain text. This should be used when the text comes from untrusted user input.
92 */
93enum Option {
94 Notify = 1,
95 AllowLink = 2,
96 Dangerous = 4,
97 NoExec = 16,
98 WindowModal = 32,
99 PlainText = 64,
100};
101
102Q_DECLARE_FLAGS(Options, Option)
103
104// This declaration must be defined before first Option is used in method signatures
105Q_DECLARE_OPERATORS_FOR_FLAGS(Options)
106
107/*!
108 * Display a "question" dialog with two action buttons.
109 *
110 * To be used for questions like "Do you want to save the message for later or discard it?".
111 *
112 * The default button is the primary button. Pressing "Esc" triggers the secondary button.
113 *
114 * \a parent the parent widget
115 *
116 * \a text the message string
117 *
118 * \a title the message box title. If an empty string, defaults to i18n("Question").
119 *
120 * \a primaryAction the action for the primary button
121 *
122 * \a secondaryAction the action for the secondary button
123 *
124 * \a dontAskAgainName If not an empty string, a checkbox is added with which
125 * further confirmation can be turned off.
126 * The string is used to lookup and store the setting
127 * in the applications config file.
128 * The setting is stored in the "Notification Messages" group.
129 * If \a dontAskAgainName starts with a ':' then the setting
130 * is stored in the global config file.
131 *
132 * \a options see Option
133 *
134 * Returns PrimaryAction if the primary button is triggered, SecondaryAction
135 * if the secondary button is triggered.
136 *
137 * \since 5.100
138 */
139KWIDGETSADDONS_EXPORT
140ButtonCode questionTwoActions(QWidget *parent,
141 const QString &text,
142 const QString &title,
143 const KGuiItem &primaryAction,
144 const KGuiItem &secondaryAction,
145 const QString &dontAskAgainName = QString(),
146 Options options = Notify);
147
148/*!
149 * Display a "question" dialog with two action buttons and a cancel button.
150 *
151 * To be used for questions like "Do you want to save the message for later or discard it?".
152 *
153 * The default button is the primary button. Pressing "Esc" triggers the cancel button.
154 *
155 * \a parent the parent widget
156 *
157 * \a text the message string
158 *
159 * \a title the message box title. If an empty string, defaults to i18n("Question").
160 *
161 * \a primaryAction the action for the primary button
162 *
163 * \a secondaryAction the action for the secondary button
164 *
165 * \a cancelAction the action for the cancel button
166 *
167 * \a dontAskAgainName If not an empty string, a checkbox is added with which
168 * further confirmation can be turned off.
169 * The string is used to lookup and store the setting
170 * in the applications config file.
171 * The setting is stored in the "Notification Messages" group.
172 * If \a dontAskAgainName starts with a ':' then the setting
173 * is stored in the global config file.
174 *
175 * \a options see Option
176 *
177 * Returns PrimaryAction if the primary button is triggered, SecondaryAction
178 * if the secondary button is triggered. Cancel if the cancel button is triggered.
179 *
180 * \since 5.100
181 */
182KWIDGETSADDONS_EXPORT
183ButtonCode questionTwoActionsCancel(QWidget *parent,
184 const QString &text,
185 const QString &title,
186 const KGuiItem &primaryAction,
187 const KGuiItem &secondaryAction,
188 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
189 const QString &dontAskAgainName = QString(),
190 Options options = Notify);
191
192/*!
193 * Display a "question" dialog with a listbox to show information to the user
194 * and two action buttons.
195 *
196 * To be used for questions like "Do you really want to delete these files?"
197 * and show the user exactly which files are going to be deleted in case.
198 *
199 * The default button is the primary button. Pressing "Esc" triggers the secondary button.
200 *
201 * \a parent the parent widget
202 *
203 * \a text the message string
204 *
205 * \a strlist List of strings to be written in the listbox. If the list is
206 * empty, it doesn't show any listbox, working as questionTwoActions().
207 *
208 * \a title the message box title. If an empty string, defaults to i18n("Question").
209 *
210 * \a primaryAction the action for the primary button
211 *
212 * \a secondaryAction the action for the secondary button
213 *
214 * \a dontAskAgainName If not an empty string, a checkbox is added with which
215 * further confirmation can be turned off.
216 * The string is used to lookup and store the setting
217 * in the applications config file.
218 * The setting is stored in the "Notification Messages" group.
219 * If \a dontAskAgainName starts with a ':' then the setting
220 * is stored in the global config file.
221 * \a options see Option
222 *
223 * Returns PrimaryAction if the primary button is triggered, SecondaryAction
224 * if the secondary button is triggered.
225 *
226 * \since 5.100
227 */
228KWIDGETSADDONS_EXPORT
229ButtonCode questionTwoActionsList(QWidget *parent,
230 const QString &text,
231 const QStringList &strlist,
232 const QString &title,
233 const KGuiItem &primaryAction,
234 const KGuiItem &secondaryAction,
235 const QString &dontAskAgainName = QString(),
236 Options options = Notify);
237
238/*!
239 * Display a "warning" dialog with two action buttons.
240 *
241 * To be used for questions like "Shall I update your configuration?".
242 * The text should explain the implication of both actions.
243 *
244 * The default button is the secondary button. Pressing "Esc" triggers the secondary button.
245 *
246 * \a parent the parent widget
247 *
248 * \a text the message string
249 *
250 * \a title the message box title. If an empty string, defaults to i18n("Warning").
251 *
252 * \a primaryAction the action for the primary button
253 *
254 * \a secondaryAction the action for the secondary button
255 *
256 * \a dontAskAgainName If not an empty string, a checkbox is added with which
257 * further confirmation can be turned off.
258 * The string is used to lookup and store the setting
259 * in the applications config file.
260 * The setting is stored in the "Notification Messages" group.
261 * If \a dontAskAgainName starts with a ':' then the setting
262 * is stored in the global config file.
263 *
264 * \a options see Options
265 *
266 * Returns \c PrimaryAction if the primary button is triggered, \c SecondaryAction
267 * if the secondary button is triggered.
268 *
269 * \since 5.100
270 */
271KWIDGETSADDONS_EXPORT
272ButtonCode warningTwoActions(QWidget *parent,
273 const QString &text,
274 const QString &title,
275 const KGuiItem &primaryAction,
276 const KGuiItem &secondaryAction,
277 const QString &dontAskAgainName = QString(),
278 Options options = Options(Notify | Dangerous));
279
280/*!
281 * Display a "warning" dialog with a listbox to show information to the user
282 * and two action buttons.
283 *
284 * To be used for questions like "Shall I update your configuration?".
285 * The text should explain the implication of both actions.
286 *
287 * The default button is the secondary button. Pressing "Esc" triggers the secondary button.
288 *
289 * \a parent the parent widget
290 *
291 * \a text the message string
292 *
293 * \a strlist List of strings to be written in the listbox. If the list is
294 * empty, it doesn't show any listbox, working as warningTwoActions.
295 *
296 * \a title the message box title. If an empty string, defaults to i18n("Warning").
297 *
298 * \a primaryAction the action for the primary button
299 *
300 * \a secondaryAction the action for the secondary button
301 *
302 * \a dontAskAgainName If not an empty string, a checkbox is added with which
303 * further confirmation can be turned off.
304 * The string is used to lookup and store the setting
305 * in the applications config file.
306 * The setting is stored in the "Notification Messages" group.
307 * If \a dontAskAgainName starts with a ':' then the setting
308 * is stored in the global config file.
309 *
310 * \a options see Options
311 *
312 * Returns PrimaryAction if the primary button is triggered, SecondaryAction
313 * if the secondary button is triggered.
314 *
315 * \since 5.100
316 */
317KWIDGETSADDONS_EXPORT
318ButtonCode warningTwoActionsList(QWidget *parent,
319 const QString &text,
320 const QStringList &strlist,
321 const QString &title,
322 const KGuiItem &primaryAction,
323 const KGuiItem &secondaryAction,
324 const QString &dontAskAgainName = QString(),
325 Options options = Options(Notify | Dangerous));
326
327/*!
328 * Display a "warning" dialog.
329 *
330 * \a parent Parent widget.
331 *
332 * \a text Message string.
333 *
334 * \a title Message box title. The application name is added to
335 * the title. The default title is i18n("Warning").
336 *
337 * \a buttonContinue The text for the first button.
338 * The default is KStandardGuiItem::cont().
339 *
340 * \a buttonCancel The text for the second button.
341 * The default is KStandardGuiItem::cancel().
342 *
343 * \a dontAskAgainName If provided, a checkbox is added with which
344 * further confirmation can be turned off.
345 * The string is used to lookup and store the setting
346 * in the applications config file.
347 * The setting is stored in the "Notification Messages" group.
348 * If \a dontAskAgainName starts with a ':' then the setting
349 * is stored in the global config file.
350 *
351 * \a options see Options
352 *
353 * Continue is returned if the Continue-button is pressed.
354 *
355 * Cancel is returned if the Cancel-button is pressed.
356 *
357 * To be used for questions like "You are about to Print. Are you sure?"
358 * the continueButton should then be labeled "Print".
359 *
360 * The default button is buttonContinue. Pressing "Esc" selects "Cancel".
361 */
362KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancel(QWidget *parent,
363 const QString &text,
364 const QString &title = QString(),
365 const KGuiItem &buttonContinue = KStandardGuiItem::cont(),
366 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(),
367 const QString &dontAskAgainName = QString(),
368 Options options = Notify);
369
370/*!
371 * Display a "warning" dialog with a collapsible "Details" section.
372 *
373 * \since 5.61
374 */
375KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelDetailed(QWidget *parent,
376 const QString &text,
377 const QString &title = QString(),
378 const KGuiItem &buttonContinue = KStandardGuiItem::cont(),
379 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(),
380 const QString &dontAskAgainName = QString(),
381 Options options = Notify,
382 const QString &details = QString());
383
384/*!
385 * Display a "warning" dialog with a listbox to show information to the user.
386 *
387 * \a parent Parent widget.
388 *
389 * \a text Message string.
390 *
391 * \a strlist List of strings to be written in the listbox. If the
392 * list is empty, it doesn't show any listbox, working
393 * as warningContinueCancel.
394 *
395 * \a title Message box title. The application name is added to
396 * the title. The default title is i18n("Warning").
397 *
398 * \a buttonContinue The text for the first button.
399 * The default is KStandardGuiItem::cont().
400 *
401 * \a buttonCancel The text for the second button.
402 * The default is KStandardGuiItem::cancel().
403 *
404 * \a dontAskAgainName If provided, a checkbox is added with which
405 * further confirmation can be turned off.
406 * The string is used to lookup and store the setting
407 * in the applications config file.
408 * The setting is stored in the "Notification Messages" group.
409 * If \a dontAskAgainName starts with a ':' then the setting
410 * is stored in the global config file.
411 *
412 * \a options see Options
413 *
414 * Continue is returned if the Continue-button is pressed.
415 *
416 * Cancel is returned if the Cancel-button is pressed.
417 *
418 * To be used for questions like "You are about to Print. Are you sure?"
419 * the continueButton should then be labeled "Print".
420 *
421 * The default button is buttonContinue. Pressing "Esc" selects "Cancel".
422 */
423KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelList(QWidget *parent,
424 const QString &text,
425 const QStringList &strlist,
426 const QString &title = QString(),
427 const KGuiItem &buttonContinue = KStandardGuiItem::cont(),
428 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(),
429 const QString &dontAskAgainName = QString(),
430 Options options = Notify);
431
432/*!
433 * Display a "warning" dialog with two action buttons and a cancel button.
434 *
435 * To be used for questions like "Shall I update your configuration?".
436 * The text should explain the implication of both actions.
437 *
438 * The default button is the cancel button. Pressing "Esc" triggers the cancel button.
439 *
440 * \a parent the parent widget
441 *
442 * \a text the message string
443 *
444 * \a title the message box title. If an empty string, defaults to i18n("Warning").
445 *
446 * \a primaryAction the action for the primary button
447 *
448 * \a secondaryAction the action for the secondary button
449 *
450 * \a cancelAction the action for the cancel button
451 *
452 * \a dontAskAgainName If not an empty string, a checkbox is added with which
453 * further confirmation can be turned off.
454 * The string is used to lookup and store the setting
455 * in the applications config file.
456 * The setting is stored in the "Notification Messages" group.
457 * If \a dontAskAgainName starts with a ':' then the setting
458 * is stored in the global config file.
459 *
460 * \a options see Options
461 *
462 * Returns PrimaryAction if the primary button is triggered, SecondaryAction
463 * if the secondary button is triggered. Cancel if the cancel button is triggered.
464 *
465 * \since 5.100
466 */
467KWIDGETSADDONS_EXPORT
468ButtonCode warningTwoActionsCancel(QWidget *parent,
469 const QString &text,
470 const QString &title,
471 const KGuiItem &primaryAction,
472 const KGuiItem &secondaryAction,
473 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
474 const QString &dontAskAgainName = QString(),
475 Options options = Options(Notify | Dangerous));
476
477/*!
478 * Display a "warning" dialog with a listbox to show information
479 * to the user, two action buttons and a cancel button.
480 *
481 * To be used for questions like "Shall I update your configuration?".
482 * The text should explain the implication of both actions.
483 *
484 * The default button is the cancel button. Pressing "Esc" triggers the cancel button.
485 *
486 * \a parent the parent widget
487 *
488 * \a text the message string
489 *
490 * \a strlist a List of strings to be written in the listbox. If the
491 * list is empty, it doesn't show any listbox, working
492 * as warningTwoActionsCancel().
493 *
494 * \a title the message box title. If an empty string, defaults to i18n("Warning").
495 *
496 * \a primaryAction the action for the primary button
497 *
498 * \a secondaryAction the action for the secondary button
499 *
500 * \a cancelAction the action for the cancel button
501 *
502 * \a dontAskAgainName If not an empty string, a checkbox is added with which
503 * further confirmation can be turned off.
504 * The string is used to lookup and store the setting
505 * in the applications config file.
506 * The setting is stored in the "Notification Messages" group.
507 * If \a dontAskAgainName starts with a ':' then the setting
508 * is stored in the global config file.
509 *
510 * \a options see Options
511 *
512 * Returns PrimaryAction if the primary button is triggered, SecondaryAction
513 * if the secondary button is triggered. Cancel if the cancel button is triggered.
514 *
515 * \since 5.100
516 */
517KWIDGETSADDONS_EXPORT
518ButtonCode warningTwoActionsCancelList(QWidget *parent,
519 const QString &text,
520 const QStringList &strlist,
521 const QString &title,
522 const KGuiItem &primaryAction,
523 const KGuiItem &secondaryAction,
524 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
525 const QString &dontAskAgainName = QString(),
526 Options options = Options(Notify | Dangerous));
527
528/*!
529 * Display an "Error" dialog.
530 *
531 * \a parent Parent widget.
532 *
533 * \a text Message string.
534 *
535 * \a title Message box title. The application name is added to
536 * the title. The default title is i18n("Error").
537 *
538 * \a options see Options
539 *
540 * Your program messed up and now it's time to inform the user.
541 * To be used for important things like "Sorry, I deleted your hard disk."
542 *
543 * The default button is "&OK". Pressing "Esc" selects the OK-button.
544 *
545 * \note The OK button will always have the i18n'ed text '&OK'.
546 */
547KWIDGETSADDONS_EXPORT void error(QWidget *parent, const QString &text, const QString &title = QString(), Options options = Notify);
548
549/*!
550 * Display an "Error" dialog.
551 *
552 * \a parent Parent widget.
553 *
554 * \a text Message string.
555 *
556 * \a title Message box title. The application name is added to
557 * the title. The default title is i18n("Error").
558 *
559 * \a buttonOk The text for the only button.
560 * The default is KStandardGuiItem::ok().
561 *
562 * \a options see Options
563 *
564 * There is only one button, therefore it's the default button, and pressing "Esc" selects it as well.
565 *
566 * \since 5.97
567 */
568KWIDGETSADDONS_EXPORT
569void error(QWidget *parent,
570 const QString &text,
571 const QString &title /*= QString()*/,
572 const KGuiItem &buttonOk /*= KStandardGuiItem::ok()*/,
573 Options options = Notify); // TODO KF6 merge with previous overload
574
575/*!
576 * Display an "Error" dialog with a listbox.
577 *
578 * \a parent Parent widget.
579 *
580 * \a text Message string.
581 *
582 * \a strlist List of strings to be written in the listbox. If the
583 * list is empty, it doesn't show any listbox, working
584 * as error().
585 *
586 * \a title Message box title. The application name is added to
587 * the title. The default title is i18n("Error").
588 *
589 * \a options see Options
590 *
591 * Your program messed up and now it's time to inform the user.
592 * To be used for important things like "Sorry, I deleted your hard disk."
593 *
594 * The default button is "&OK". Pressing "Esc" selects the OK-button.
595 *
596 * \note The OK button will always have the i18n'ed text '&OK'.
597 */
598KWIDGETSADDONS_EXPORT void
599errorList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title = QString(), Options options = Notify);
600
601/*!
602 * Displays an "Error" dialog with a "Details >>" button.
603 *
604 * \a parent Parent widget.
605 *
606 * \a text Message string.
607 *
608 * \a details Detailed message string.
609 *
610 * \a title Message box title. The application name is added to
611 * the title. The default title is i18n("Error").
612 *
613 * \a options see Options
614 *
615 * Your program messed up and now it's time to inform the user.
616 * To be used for important things like "Sorry, I deleted your hard disk."
617 *
618 * The \a details message can contain additional information about
619 * the problem and can be shown on request to advanced/interested users.
620 *
621 * The default button is "&OK". Pressing "Esc" selects the OK-button.
622 *
623 * \note The OK button will always have the i18n'ed text '&OK'.
624 */
625KWIDGETSADDONS_EXPORT void
626detailedError(QWidget *parent, const QString &text, const QString &details, const QString &title = QString(), Options options = Notify);
627
628/*!
629 * Displays an "Error" dialog with a "Details >>" button.
630 *
631 * \a parent Parent widget.
632 *
633 * \a text Message string.
634 *
635 * \a details Detailed message string.
636 *
637 * \a title Message box title. The application name is added to
638 * the title. The default title is i18n("Error").
639 *
640 * \a buttonOk The text for the only button.
641 * The default is KStandardGuiItem::ok().
642 *
643 * \a options see Options
644 *
645 * Your program messed up and now it's time to inform the user.
646 * To be used for important things like "Sorry, I deleted your hard disk."
647 *
648 * The \a details message can contain additional information about
649 * the problem and can be shown on request to advanced/interested users.
650 *
651 * There is only one button, therefore it's the default button, and pressing "Esc" selects it as well.
652 *
653 * \since 5.97
654 */
655KWIDGETSADDONS_EXPORT
656void detailedError(QWidget *parent,
657 const QString &text,
658 const QString &details,
659 const QString &title /*= QString()*/,
660 const KGuiItem &buttonOk /*= KStandardGuiItem::ok()*/,
661 Options options = Notify); // TODO KF6 merge with previous overload
662
663/*!
664 * Display an "Information" dialog.
665 *
666 * \a parent Parent widget.
667 *
668 * \a text Message string.
669 *
670 * \a title Message box title. The application name is added to
671 * the title. The default title is i18n("Information").
672 *
673 * \a dontShowAgainName If provided, a checkbox is added with which
674 * further notifications can be turned off.
675 * The string is used to lookup and store the setting
676 * in the applications config file.
677 * The setting is stored in the "Notification Messages" group.
678 *
679 * \a options see Options
680 *
681 * Your program wants to tell the user something.
682 * To be used for things like:
683 * "Your bookmarks have been rearranged."
684 *
685 * The default button is "&OK". Pressing "Esc" selects the OK-button.
686 *
687 * \note The OK button will always have the i18n'ed text '&OK'.
688 */
689KWIDGETSADDONS_EXPORT void
690information(QWidget *parent, const QString &text, const QString &title = QString(), const QString &dontShowAgainName = QString(), Options options = Notify);
691
692/*!
693 * Display an "Information" dialog with a listbox.
694 *
695 * \a parent Parent widget.
696 *
697 * \a text Message string.
698 *
699 * \a strlist List of strings to be written in the listbox. If the
700 * list is empty, it doesn't show any listbox, working
701 * as information.
702 *
703 * \a title Message box title. The application name is added to
704 * the title. The default title is i18n("Information").
705 *
706 * \a dontShowAgainName If provided, a checkbox is added with which
707 * further notifications can be turned off.
708 * The string is used to lookup and store the setting
709 * in the applications config file.
710 * The setting is stored in the "Notification Messages" group.
711 *
712 * \a options see Options
713 *
714 *
715 * Your program wants to tell the user something.
716 * To be used for things like:
717 * "The following bookmarks have been rearranged:"
718 *
719 * The default button is "&OK". Pressing "Esc" selects the OK-button.
720 *
721 * \note The OK button will always have the i18n'ed text '&OK'.
722 */
723KWIDGETSADDONS_EXPORT void informationList(QWidget *parent,
724 const QString &text,
725 const QStringList &strlist,
726 const QString &title = QString(),
727 const QString &dontShowAgainName = QString(),
728 Options options = Notify);
729
730/*!
731 * Enable all messages which have been turned off with the
732 *
733 * \a dontShowAgainName feature.
734 */
735KWIDGETSADDONS_EXPORT void enableAllMessages();
736
737/*!
738 * Re-enable a specific \a dontShowAgainName messages that had
739 * previously been turned off.
740 *
741 * \sa saveDontShowAgainTwoActions()
742 * \sa saveDontShowAgainContinue()
743 */
744KWIDGETSADDONS_EXPORT void enableMessage(const QString &dontShowAgainName);
745
746/*!
747 * Alternate method to show a messagebox:
748 *
749 * \a parent Parent widget.
750 *
751 * \a type type of message box: QuestionTwoActions, WarningTwoActions, WarningContinueCancel...
752 *
753 * \a text Message string.
754 *
755 * \a title Message box title.
756 *
757 * \a primaryAction The KGuiItem for the first button.
758 *
759 * \a secondaryAction The KGuiItem for the second button.
760 *
761 * \a cancelAction The text for the third button.
762 * The default is KStandardGuiItem::cancel().
763 *
764 * \a dontShowAskAgainName If provided, a checkbox is added with which
765 * further questions/information can be turned off. If turned off
766 * all questions will be automatically answered with the
767 * last answer (either PrimaryAction or SecondaryAction),
768 * if the message box needs an answer.
769 * The string is used to lookup and store the setting
770 * in the applications config file.
771 *
772 * \a options see Options
773 *
774 * Note: for ContinueCancel, primaryAction is the continue button and secondaryAction is unused.
775 * and for Information, none is used.
776 *
777 * Returns a button code, as defined in KMessageBox.
778 */
779KWIDGETSADDONS_EXPORT
780ButtonCode messageBox(QWidget *parent,
781 DialogType type,
782 const QString &text,
783 const QString &title,
784 const KGuiItem &primaryAction,
785 const KGuiItem &secondaryAction,
786 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
787 const QString &dontShowAskAgainName = QString(),
788 Options options = Notify);
789
790/*!
791 * \a dontShowAgainName the name that identifies the message box.
792 * If empty, \c true is always returned.
793 *
794 * \a result reference to a variable to be set to the choice (\c PrimaryAction or \c SecondaryAction)
795 * that was chosen the last time the message box was shown.
796 * Only meaningful if the message box should not be shown.
797 *
798 * Returns \c true if the corresponding two actions message box should be shown, \c false otherwise.
799 *
800 * \since 5.100
801 */
802KWIDGETSADDONS_EXPORT
803bool shouldBeShownTwoActions(const QString &dontShowAgainName, ButtonCode &result);
804
805/*!
806 * Returns \c true if the corresponding continue/cancel message box should be
807 * shown.
808 *
809 * \a dontShowAgainName the name that identify the message box. If
810 * empty, true is always returned.
811 */
812KWIDGETSADDONS_EXPORT bool shouldBeShownContinue(const QString &dontShowAgainName);
813
814/*!
815 * Save the fact that a two actions message box should not be shown again.
816 *
817 * \a dontShowAgainName the name that identifies the message box.
818 * If empty, this method does nothing.
819 *
820 * \a result the value (\c PrimaryAction or \c SecondaryAction) that should be used
821 * as the result for the message box.
822 *
823 * \since 5.100
824 */
825KWIDGETSADDONS_EXPORT
826void saveDontShowAgainTwoActions(const QString &dontShowAgainName, ButtonCode result);
827
828/*!
829 * Save the fact that the continue/cancel message box should not be shown
830 * again.
831 *
832 * \a dontShowAgainName the name that identify the message box. If
833 * empty, this method does nothing.
834 */
835KWIDGETSADDONS_EXPORT void saveDontShowAgainContinue(const QString &dontShowAgainName);
836
837/*!
838 * Use \a cfg for all settings related to the dontShowAgainName feature.
839 *
840 * If \a cfg is 0 (default) KGlobal::config() will be used.
841 */
842KWIDGETSADDONS_EXPORT void setDontShowAgainConfig(KConfig *cfg);
843
844/*!
845 * Use \a dontAskAgainInterface for all settings related to the dontShowAgain feature.
846 *
847 * This method does not take ownership of \a dontAskAgainInterface.
848 *
849 * \since 5.0
850 */
851KWIDGETSADDONS_EXPORT void setDontShowAgainInterface(KMessageBoxDontAskAgainInterface *dontAskAgainInterface);
852
853/*!
854 * Use \a notifyInterface to send notifications.
855 *
856 * This method does not take ownership of \a notifyInterface.
857 *
858 * \since 5.0
859 */
860KWIDGETSADDONS_EXPORT void setNotifyInterface(KMessageBoxNotifyInterface *notifyInterface);
861
862/*!
863 * Create content and layout of a standard dialog
864 *
865 * \a dialog The parent dialog base
866 *
867 * \a buttons a QDialogButtonBox instance. This function will take care of connecting to it.
868 *
869 * \a icon Which predefined icon the message box shall show.
870 *
871 * \a text Message string.
872 *
873 * \a strlist List of strings to be written in the listbox.
874 * If the list is empty, it doesn't show any listbox
875 *
876 * \a ask The text of the checkbox. If empty none will be shown.
877 *
878 * \a checkboxReturn The result of the checkbox. If it's initially
879 * true then the checkbox will be checked by default.
880 * May be a null pointer. Incompatible with NoExec.
881 *
882 * \a options see Options
883 *
884 * \a details Detailed message string.
885 *
886 * Returns a QDialogButtonBox::StandardButton button code, not a KMessageBox
887 * button code, based on the buttonmask given to the constructor of
888 * the \a dialog (ie. will return QDialogButtonBox::Yes instead of
889 * KMessageBox::PrimaryAction). Will return QDialogButtonBox::NoButton if the
890 * message box is queued for display instead of exec()ed immediately
891 * or if the option NoExec is set.
892 *
893 * \note Unless NoExec is used,
894 * the \a dialog that is passed in is deleted by this
895 * function. Do not delete it yourself.
896 */
897KWIDGETSADDONS_EXPORT QDialogButtonBox::StandardButton createKMessageBox(QDialog *dialog,
898 QDialogButtonBox *buttons,
899 QMessageBox::Icon icon, // krazy:exclude=qclasses
900 const QString &text,
901 const QStringList &strlist,
902 const QString &ask,
903 bool *checkboxReturn,
904 Options options,
905 const QString &details = QString());
906
907/*!
908 * Create content and layout of a standard dialog
909 *
910 * \a dialog The parent dialog base
911 *
912 * \a buttons a QDialogButtonBox instance. This function will take care of connecting to it.
913 *
914 * \a icon A QPixmap containing the icon to be displayed in the
915 * dialog next to the text.
916 *
917 * \a text Message string.
918 *
919 * \a strlist List of strings to be written in the listbox.
920 * If the list is empty, it doesn't show any listbox
921 *
922 * \a ask The text of the checkbox. If empty none will be shown.
923 *
924 * \a checkboxReturn The result of the checkbox. If it's initially
925 * true then the checkbox will be checked by default.
926 * May be a null pointer. Incompatible with NoExec.
927 *
928 * \a options see Options
929 *
930 * \a details Detailed message string.
931 *
932 * \a notifyType The type of notification to send when this message
933 * is presentend.
934 *
935 * Returns a QDialogButtonBox::StandardButton button code, not a KMessageBox
936 * button code, based on the buttonmask given to the constructor of
937 * the \a dialog (ie. will return QDialogButtonBox::Yes instead of
938 * KMessageBox::PrimaryAction). Will return QDialogButtonBox::NoButton if the
939 * message box is queued for display instead of exec()ed immediately
940 * or if the option NoExec is set.
941 *
942 * \note Unless NoExec is used,
943 * the \a dialog that is passed in is deleted by this
944 * function. Do not delete it yourself.
945 */
946KWIDGETSADDONS_EXPORT QDialogButtonBox::StandardButton createKMessageBox(QDialog *dialog,
947 QDialogButtonBox *buttons,
948 const QIcon &icon,
949 const QString &text,
950 const QStringList &strlist,
951 const QString &ask,
952 bool *checkboxReturn,
953 Options options,
954 const QString &details = QString(),
955 QMessageBox::Icon notifyType = QMessageBox::Information); // krazy:exclude=qclasses
956
957/*!
958 * This function accepts the window id of the parent window, instead
959 * of QWidget*. It should be used only when necessary.
960 *
961 * \sa questionTwoActions()
962 * \since 5.100
963 */
964KWIDGETSADDONS_EXPORT
965ButtonCode questionTwoActionsWId(WId parent_id,
966 const QString &text,
967 const QString &title,
968 const KGuiItem &primaryAction,
969 const KGuiItem &secondaryAction,
970 const QString &dontAskAgainName = QString(),
971 Options options = Notify);
972
973/*!
974 * This function accepts the window id of the parent window, instead
975 * of QWidget*. It should be used only when necessary.
976 *
977 * \sa questionTwoActionsCancel()
978 * \since 5.100
979 */
980KWIDGETSADDONS_EXPORT
981ButtonCode questionTwoActionsCancelWId(WId parent_id,
982 const QString &text,
983 const QString &title,
984 const KGuiItem &primaryAction,
985 const KGuiItem &secondaryAction,
986 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
987 const QString &dontAskAgainName = QString(),
988 Options options = Notify);
989
990/*!
991 * This function accepts the window id of the parent window, instead
992 * of QWidget*. It should be used only when necessary.
993 *
994 * \sa questionTwoActionsList()
995 * \since 5.100
996 */
997KWIDGETSADDONS_EXPORT
998ButtonCode questionTwoActionsListWId(WId parent_id,
999 const QString &text,
1000 const QStringList &strlist,
1001 const QString &title,
1002 const KGuiItem &primaryAction,
1003 const KGuiItem &secondaryAction,
1004 const QString &dontAskAgainName = QString(),
1005 Options options = Notify);
1006
1007/*!
1008 * This function accepts the window id of the parent window, instead
1009 * of QWidget*. It should be used only when necessary.
1010 *
1011 * \sa warningTwoActions()
1012 * \since 5.100
1013 */
1014KWIDGETSADDONS_EXPORT
1015ButtonCode warningTwoActionsWId(WId parent_id,
1016 const QString &text,
1017 const QString &title,
1018 const KGuiItem &primaryAction,
1019 const KGuiItem &secondaryAction,
1020 const QString &dontAskAgainName = QString(),
1021 Options options = Options(Notify | Dangerous));
1022
1023/*!
1024 * This function accepts the window id of the parent window, instead
1025 * of QWidget*. It should be used only when necessary.
1026 *
1027 * \sa warningTwoActionsList()
1028 * \since 5.100
1029 */
1030KWIDGETSADDONS_EXPORT
1031ButtonCode warningTwoActionsListWId(WId parent_id,
1032 const QString &text,
1033 const QStringList &strlist,
1034 const QString &title,
1035 const KGuiItem &primaryAction,
1036 const KGuiItem &secondaryAction,
1037 const QString &dontAskAgainName = QString(),
1038 Options options = Options(Notify | Dangerous));
1039
1040/*!
1041 * This function accepts the window id of the parent window, instead
1042 * of QWidget*. It should be used only when necessary.
1043 */
1044KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelWId(WId parent_id,
1045 const QString &text,
1046 const QString &title = QString(),
1047 const KGuiItem &buttonContinue = KStandardGuiItem::cont(),
1048 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(),
1049 const QString &dontAskAgainName = QString(),
1050 Options options = Notify);
1051
1052/*!
1053 * This function accepts the window id of the parent window, instead
1054 * of QWidget*. It should be used only when necessary.
1055 */
1056KWIDGETSADDONS_EXPORT ButtonCode warningContinueCancelListWId(WId parent_id,
1057 const QString &text,
1058 const QStringList &strlist,
1059 const QString &title = QString(),
1060 const KGuiItem &buttonContinue = KStandardGuiItem::cont(),
1061 const KGuiItem &buttonCancel = KStandardGuiItem::cancel(),
1062 const QString &dontAskAgainName = QString(),
1063 Options options = Notify);
1064
1065/*!
1066 * This function accepts the window id of the parent window, instead
1067 * of QWidget*. It should be used only when necessary.
1068 *
1069 * \sa warningTwoActionsCancel()
1070 * \since 5.100
1071 */
1072KWIDGETSADDONS_EXPORT
1073ButtonCode warningTwoActionsCancelWId(WId parent_id,
1074 const QString &text,
1075 const QString &title,
1076 const KGuiItem &primaryAction,
1077 const KGuiItem &secondaryAction,
1078 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
1079 const QString &dontAskAgainName = QString(),
1080 Options options = Options(Notify | Dangerous));
1081
1082/*!
1083 * This function accepts the window id of the parent window, instead
1084 * of QWidget*. It should be used only when necessary.
1085 *
1086 * \sa warningTwoActionsCancelList()
1087 * \since 5.100
1088 */
1089KWIDGETSADDONS_EXPORT
1090ButtonCode warningTwoActionsCancelListWId(WId parent_id,
1091 const QString &text,
1092 const QStringList &strlist,
1093 const QString &title,
1094 const KGuiItem &primaryAction,
1095 const KGuiItem &secondaryAction,
1096 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
1097 const QString &dontAskAgainName = QString(),
1098 Options options = Options(Notify | Dangerous));
1099
1100/*!
1101 * This function accepts the window id of the parent window, instead
1102 * of QWidget*. It should be used only when necessary.
1103 */
1104KWIDGETSADDONS_EXPORT void errorWId(WId parent_id, const QString &text, const QString &title = QString(), Options options = Notify);
1105
1106/*!
1107 * This function accepts the window id of the parent window, instead
1108 * of QWidget*. It should be used only when necessary.
1109 */
1110KWIDGETSADDONS_EXPORT void
1111errorListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title = QString(), Options options = Notify);
1112
1113/*!
1114 * This function accepts the window id of the parent window, instead
1115 * of QWidget*. It should be used only when necessary.
1116 */
1117KWIDGETSADDONS_EXPORT void
1118detailedErrorWId(WId parent_id, const QString &text, const QString &details, const QString &title = QString(), Options options = Notify);
1119
1120/*!
1121 * This function accepts the window id of the parent window, instead
1122 * of QWidget*. It should be used only when necessary.
1123 * \since 5.97
1124 */
1125KWIDGETSADDONS_EXPORT
1126void detailedErrorWId(WId parent_id,
1127 const QString &text,
1128 const QString &details,
1129 const QString &title /*= QString()*/,
1130 const KGuiItem &buttonOk /*= KStandardGuiItem::ok()*/,
1131 Options options = Notify); // TODO KF6 merge with previous overload
1132
1133/*!
1134 * This function accepts the window id of the parent window, instead
1135 * of QWidget*. It should be used only when necessary.
1136 */
1137KWIDGETSADDONS_EXPORT void
1138informationWId(WId parent_id, const QString &text, const QString &title = QString(), const QString &dontShowAgainName = QString(), Options options = Notify);
1139
1140/*!
1141 * This function accepts the window id of the parent window, instead
1142 * of QWidget*. It should be used only when necessary.
1143 */
1144KWIDGETSADDONS_EXPORT void informationListWId(WId parent_id,
1145 const QString &text,
1146 const QStringList &strlist,
1147 const QString &title = QString(),
1148 const QString &dontShowAgainName = QString(),
1149 Options options = Notify);
1150
1151/*!
1152 * This function accepts the window id of the parent window, instead
1153 * of QWidget*. It should be used only when necessary.
1154 */
1155KWIDGETSADDONS_EXPORT
1156ButtonCode messageBoxWId(WId parent_id,
1157 DialogType type,
1158 const QString &text,
1159 const QString &title,
1160 const KGuiItem &primaryAction,
1161 const KGuiItem &secondaryAction,
1162 const KGuiItem &cancelAction = KStandardGuiItem::cancel(),
1163 const QString &dontShowAskAgainName = QString(),
1164 Options options = Notify);
1165}
1166
1167#endif
1168

source code of kwidgetsaddons/src/kmessagebox.h