KWidgetsAddons

kmessagebox.h
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
24class QDialog;
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 */
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
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
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
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
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
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
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
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
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
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 */
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 */
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
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
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
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
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
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
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
An abstract class for setting the text, icon, tooltip and WhatsThis data on a GUI item (e....
Definition kguiitem.h:34
Easy message dialog box.
void saveDontShowAgainTwoActions(const QString &dontShowAgainName, ButtonCode result)
Save the fact that a two actions message box should not be shown again.
ButtonCode warningContinueCancel(QWidget *parent, const QString &text, const QString &title, const KGuiItem &buttonContinue, const KGuiItem &buttonCancel, const QString &dontAskAgainName, Options options)
Display a "warning" dialog.
ButtonCode warningTwoActionsCancelListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &buttonCancel, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
void error(QWidget *parent, const QString &text, const QString &title, Options options)
Display an "Error" dialog.
ButtonCode warningTwoActionsListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
ButtonCode warningContinueCancelListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &buttonContinue, const KGuiItem &buttonCancel, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
ButtonCode messageBoxWId(WId parent_id, DialogType type, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &cancelAction, const QString &dontShow, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
void saveDontShowAgainContinue(const QString &dontShowAgainName)
Save the fact that the continue/cancel message box should not be shown again.
ButtonCode questionTwoActionsWId(WId parent_id, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
void errorList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title, Options options)
Display an "Error" dialog with a listbox.
ButtonCode warningTwoActions(QWidget *parent, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
Display a "warning" dialog with two action buttons.
void enableAllMessages()
Enable all messages which have been turned off with the dontShowAgainName feature.
ButtonCode questionTwoActionsCancelWId(WId parent_id, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &cancelAction, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
ButtonCode warningTwoActionsWId(WId parent_id, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
ButtonCode warningTwoActionsList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
Display a "warning" dialog with a listbox to show information to the user and two action buttons.
void errorWId(WId parent_id, const QString &text, const QString &title, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
void informationList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title, const QString &dontShowAgainName, Options options)
Display an "Information" dialog with a listbox.
void informationListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title, const QString &dontShowAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
ButtonCode warningContinueCancelList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &buttonContinue, const KGuiItem &buttonCancel, const QString &dontAskAgainName, Options options)
Display a "warning" dialog with a listbox to show information to the user.
void detailedErrorWId(WId parent_id, const QString &text, const QString &details, const QString &title, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
void setNotifyInterface(KMessageBoxNotifyInterface *notifyInterface)
Use notifyInterface to send notifications.
void informationWId(WId parent_id, const QString &text, const QString &title, const QString &dontShowAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
ButtonCode
Button types.
Definition kmessagebox.h:48
@ PrimaryAction
Primary action button;.
Definition kmessagebox.h:51
@ SecondaryAction
Secondary action button;.
Definition kmessagebox.h:52
@ Continue
Continue button.
Definition kmessagebox.h:53
@ Cancel
Cancel button.
Definition kmessagebox.h:50
@ Ok
Ok button.
Definition kmessagebox.h:49
void information(QWidget *parent, const QString &text, const QString &title, const QString &dontShowAgainName, Options options)
Display an "Information" dialog.
bool shouldBeShownContinue(const QString &dontShowAgainName)
ButtonCode questionTwoActionsList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
Display a "question" dialog with a listbox to show information to the user and two action buttons.
ButtonCode messageBox(QWidget *parent, DialogType type, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &buttonCancel, const QString &dontShow, Options options)
Alternate method to show a messagebox:
bool shouldBeShownTwoActions(const QString &dontShowAgainName, ButtonCode &result)
ButtonCode warningContinueCancelDetailed(QWidget *parent, const QString &text, const QString &title, const KGuiItem &buttonContinue, const KGuiItem &buttonCancel, const QString &dontAskAgainName, Options options, const QString &details)
Display a "warning" dialog with a collapsible "Details" section.
QFlags< Option > Options
Stores a combination of Option values.
Definition kmessagebox.h:82
ButtonCode questionTwoActionsCancel(QWidget *parent, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &cancelAction, const QString &dontAskAgainName, Options options)
Display a "question" dialog with two action buttons and a cancel button.
ButtonCode warningTwoActionsCancelWId(WId parent_id, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &buttonCancel, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
QDialogButtonBox::StandardButton createKMessageBox(QDialog *dialog, QDialogButtonBox *buttons, QMessageBox::Icon icon, const QString &text, const QStringList &strlist, const QString &ask, bool *checkboxReturn, Options options, const QString &details)
Create content and layout of a standard dialog.
void setDontShowAgainInterface(KMessageBoxDontAskAgainInterface *dontAskAgainInterface)
Use dontAskAgainInterface for all settings related to the dontShowAgain feature.
@ WindowModal
The window is to be modal relative to its parent. By default, it is application modal.
Definition kmessagebox.h:76
@ NoExec
Do not call exec() in createKMessageBox()
Definition kmessagebox.h:75
@ Dangerous
The action to be confirmed by the dialog is a potentially destructive one.
Definition kmessagebox.h:73
@ AllowLink
The message may contain links.
Definition kmessagebox.h:72
ButtonCode warningTwoActionsCancelList(QWidget *parent, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &cancelAction, const QString &dontAskAgainName, Options options)
Display a "warning" dialog with a listbox to show information to the user, two action buttons and a c...
ButtonCode warningContinueCancelWId(WId parent_id, const QString &text, const QString &title, const KGuiItem &buttonContinue, const KGuiItem &buttonCancel, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
void detailedError(QWidget *parent, const QString &text, const QString &details, const QString &title, Options options)
Displays an "Error" dialog with a "Details >>" button.
@ Error
Error dialog.
Definition kmessagebox.h:63
@ WarningTwoActionsCancel
Warning dialog with two buttons and Cancel;.
Definition kmessagebox.h:60
@ QuestionTwoActionsCancel
Question dialog with two buttons and Cancel;.
Definition kmessagebox.h:64
@ QuestionTwoActions
Question dialog with two buttons;.
Definition kmessagebox.h:57
@ WarningContinueCancel
Warning dialog with Continue and Cancel.
Definition kmessagebox.h:59
@ WarningTwoActions
Warning dialog with two buttons;.
Definition kmessagebox.h:58
@ Information
Information dialog.
Definition kmessagebox.h:61
void errorListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
void setDontShowAgainConfig(KConfig *cfg)
Use cfg for all settings related to the dontShowAgainName feature.
ButtonCode questionTwoActions(QWidget *parent, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
Display a "question" dialog with two action buttons.
ButtonCode questionTwoActionsListWId(WId parent_id, const QString &text, const QStringList &strlist, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const QString &dontAskAgainName, Options options)
This function accepts the window id of the parent window, instead of QWidget*.
ButtonCode warningTwoActionsCancel(QWidget *parent, const QString &text, const QString &title, const KGuiItem &primaryAction, const KGuiItem &secondaryAction, const KGuiItem &cancelAction, const QString &dontAskAgainName, Options options)
Display a "warning" dialog with two action buttons and a cancel button.
void enableMessage(const QString &dontShowAgainName)
Re-enable a specific dontShowAgainName messages that had previously been turned off.
KGuiItem cont()
Returns the 'Continue' gui item.
KGuiItem cancel()
Returns the 'Cancel' gui item.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 1 2024 18:49:18 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.