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