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

source code of kwidgetsaddons/src/kmessagebox.h