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

KDE's Doxygen guidelines are available online.