diff options
Diffstat (limited to 'tdeui/kmessagebox.h')
| -rw-r--r-- | tdeui/kmessagebox.h | 1166 |
1 files changed, 1166 insertions, 0 deletions
diff --git a/tdeui/kmessagebox.h b/tdeui/kmessagebox.h new file mode 100644 index 000000000..a543e106f --- /dev/null +++ b/tdeui/kmessagebox.h @@ -0,0 +1,1166 @@ +/* This file is part of the KDE libraries + Copyright (C) 1999 Waldo Bastian (bastian@kde.org) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; version 2 + of the License. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ +#ifndef _KMESSAGEBOX_H_ +#define _KMESSAGEBOX_H_ + +#include <tqstring.h> +#include <tqmessagebox.h> + +#include <kguiitem.h> +#include <kstdguiitem.h> + +class TQWidget; +class TQStringList; +class KConfig; +class KDialogBase; + + /** + * Easy message dialog box. + * + * Provides convenience functions for some i18n'ed standard dialogs. + * + * The text in message boxes is wrapped automatically. The text may either + * be plaintext or richtext. If the text is plaintext, a newline-character + * may be used to indicate the end of a paragraph. + * + * @author Waldo Bastian (bastian@kde.org) + */ +class KDEUI_EXPORT KMessageBox +{ +public: + /** + * Button types. + **/ + enum ButtonCode + { + Ok = 1, + Cancel = 2, + Yes = 3, + No = 4, + Continue = 5 + }; + + enum DialogType + { + QuestionYesNo = 1, + WarningYesNo = 2, + WarningContinueCancel = 3, + WarningYesNoCancel = 4, + Information = 5, + // Reserved for: SSLMessageBox = 6 + Sorry = 7, + Error = 8, + QuestionYesNoCancel = 9 + }; + + enum OptionsType + { + Notify = 1, ///< Emit a KNotifyClient event + AllowLink = 2, ///< The message may contain links. + Dangerous = 4, ///< The action to be confirmed by the dialog is a potentially destructive one + PlainCaption = 8, /**< Do not use KApplication::makeStdCaption() + @since 3.4 + */ + NoExec = 16 /**< Do not call exec() in createKMessageBox() + @since 3.4 + */ + }; + + /** + * Display a simple "question" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Question"). + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontAskAgainName If provided, a checkbox is added with which + * further confirmation can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * @return 'Yes' is returned if the Yes-button is pressed. 'No' is returned + * if the No-button is pressed. + * + * To be used for questions like "Do you have a printer?" + * + * The default button is "Yes". Pressing "Esc" selects "No". + */ + + static int questionYesNo(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int questionYesNoWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + /** + * Display a simple "question" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Question"). + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontAskAgainName If provided, a checkbox is added with which + * further confirmation can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * @return 'Yes' is returned if the Yes-button is pressed. 'No' is returned + * if the No-button is pressed. + * + * To be used for questions like "Do you want to discard the message or save it for later?", + * + * The default button is "Yes". Pressing "Esc" selects "Cancel". + * + * NOTE: The cancel button will always have the i18n'ed text '&Cancel'. + */ + + static int questionYesNoCancel(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int questionYesNoCancelWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * Display a "question" dialog with a listbox to show information to the user + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. If the list is + * empty, it doesn't show any listbox, working as questionYesNo. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Question"). + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontAskAgainName If provided, a checkbox is added with which + * further confirmation can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * @return 'Yes' is returned if the Yes-button is pressed. 'No' is returned + * if the No-button is pressed. + * + * To be used for questions like "Do you really want to delete these files?" + * And show the user exactly which files are going to be deleted in case + * he presses "Yes" + * + * The default button is "Yes". Pressing "Esc" selects "No". + */ + + static int questionYesNoList(TQWidget *parent, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int questionYesNoListWId(WId parent_id, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * Display a "warning" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Warning"). + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontAskAgainName If provided, a checkbox is added with which + * further confirmation can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * @return @p Yes is returned if the Yes-button is pressed. @p No is returned + * if the No-button is pressed. + * + * To be used for questions "Shall I update your configuration?" + * The text should explain the implication of both options. + * + * The default button is "No". Pressing "Esc" selects "No". + */ + static int warningYesNo(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify | Dangerous); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int warningYesNoWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify | Dangerous); + + /** + * Display a "warning" dialog with a listbox to show information to the user + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. If the list is + * empty, it doesn't show any listbox, working as questionYesNo. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Question"). + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontAskAgainName If provided, a checkbox is added with which + * further confirmation can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * @return 'Yes' is returned if the Yes-button is pressed. 'No' is returned + * if the No-button is pressed. + * + * To be used for questions like "Do you really want to delete these files?" + * And show the user exactly which files are going to be deleted in case + * he presses "Yes" + * + * The default button is "No". Pressing "Esc" selects "No". + */ + + static int warningYesNoList(TQWidget *parent, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify | Dangerous); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int warningYesNoListWId(WId parent_id, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify | Dangerous); + + /** + * Display a "warning" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Warning"). + * @param buttonContinue The text for the first button. + * @param dontAskAgainName If provided, a checkbox is added with which + * further confirmation can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * The second button always has the text "Cancel". + * + * @return @p Continue is returned if the Continue-button is pressed. + * @p Cancel is returned if the Cancel-button is pressed. + * + * To be used for questions like "You are about to Print. Are you sure?" + * the continueButton should then be labeled "Print". + * + * The default button is buttonContinue. Pressing "Esc" selects "Cancel". + */ + static int warningContinueCancel(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonContinue = KStdGuiItem::cont(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int warningContinueCancelWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonContinue = KStdGuiItem::cont(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * Display a "warning" dialog with a listbox to show information to the user. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. If the + * list is empty, it doesn't show any listbox, working + * as warningContinueCancel. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Warning"). + * @param buttonContinue The text for the first button. + * @param dontAskAgainName If provided, a checkbox is added with which + * further confirmation can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * + * @param options see OptionsType + * + * The second button always has the text "Cancel". + * + * @return @p Continue is returned if the Continue-button is pressed. + * @p Cancel is returned if the Cancel-button is pressed. + * + * To be used for questions like "You are about to Print. Are you sure?" + * the continueButton should then be labeled "Print". + * + * The default button is buttonContinue. Pressing "Esc" selects "Cancel". + */ + static int warningContinueCancelList(TQWidget *parent, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonContinue = KStdGuiItem::cont(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int warningContinueCancelListWId(WId parent_id, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonContinue = KStdGuiItem::cont(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * Display a Yes/No/Cancel "warning" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Warning"). + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontAskAgainName If provided, a checkbox is added with which + * further questions can be turned off. If turned off + * all questions will be automatically answered with the + * last answer (either Yes or No). + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * @return @p Yes is returned if the Yes-button is pressed. @p No is returned + * if the No-button is pressed. @p Cancel is retunred if the Cancel- + * button is pressed. + * + * To be used for questions "Do you want to save your changes?" + * The text should explain the implication of choosing 'No'. + * + * The default button is "Yes". Pressing "Esc" selects "Cancel" + * + * NOTE: The cancel button will always have the i18n'ed text '&Cancel'. + */ + + static int warningYesNoCancel(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int warningYesNoCancelWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * Display a Yes/No/Cancel "warning" dialog with a listbox to show information + * to the user. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. If the + * list is empty, it doesn't show any listbox, working + * as warningYesNoCancel. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Warning"). + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontAskAgainName If provided, a checkbox is added with which + * further questions can be turned off. If turned off + * all questions will be automatically answered with the + * last answer (either Yes or No). + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * If @p dontAskAgainName starts with a ':' then the setting + * is stored in the global config file. + * @param options see OptionsType + * + * @return @p Yes is returned if the Yes-button is pressed. @p No is returned + * if the No-button is pressed. @p Cancel is retunred if the Cancel- + * button is pressed. + * + * To be used for questions "Do you want to save your changes?" + * The text should explain the implication of choosing 'No'. + * + * The default button is "Yes". Pressing "Esc" selects "Cancel" + * + * NOTE: The cancel button will always have the i18n'ed text '&Cancel'. + * + * @since 3.2 + */ + static int warningYesNoCancelList(TQWidget *parent, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int warningYesNoCancelListWId(WId parent_id, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontAskAgainName = TQString::null, + int options = Notify); + + /** + * Display an "Error" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Error"). + * @param options see OptionsType + * + * Your program messed up and now it's time to inform the user. + * To be used for important things like "Sorry, I deleted your hard disk." + * + * If your program detects the action specified by the user is somehow + * not allowed, this should never be reported with error(). Use sorry() + * instead to explain to the user that this action is not allowed. + * + * The default button is "&OK". Pressing "Esc" selects the OK-button. + * + * NOTE: The OK button will always have the i18n'ed text '&OK'. + */ + + static void error(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * + * @since 3.2 + */ + static void errorWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * Display an "Error" dialog with a listbox. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. If the + * list is empty, it doesn't show any listbox, working + * as error(). + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Error"). + * @param options see OptionsType + * + * Your program messed up and now it's time to inform the user. + * To be used for important things like "Sorry, I deleted your hard disk." + * + * If your program detects the action specified by the user is somehow + * not allowed, this should never be reported with error(). Use sorry() + * instead to explain to the user that this action is not allowed. + * + * The default button is "&OK". Pressing "Esc" selects the OK-button. + * + * NOTE: The OK button will always have the i18n'ed text '&OK'. + * + * @since 3.4 + */ + + static void errorList(TQWidget *parent, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.4 + */ + + static void errorListWId(WId parent_id, + const TQString &text, + const TQStringList &strlist, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * Displays an "Error" dialog with a "Details >>" button. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param details Detailed message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Error"). + * @param options see OptionsType + * + * Your program messed up and now it's time to inform the user. + * To be used for important things like "Sorry, I deleted your hard disk." + * + * The @p details message can conatin additional information about + * the problem and can be shown on request to advanced/interested users. + * + * If your program detects the action specified by the user is somehow + * not allowed, this should never be reported with error(). Use sorry() + * instead to explain to the user that this action is not allowed. + * + * The default button is "&OK". Pressing "Esc" selects the OK-button. + * + * NOTE: The OK button will always have the i18n'ed text '&OK'. + */ + static void detailedError(TQWidget *parent, + const TQString &text, + const TQString &details, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void detailedErrorWId(WId parent_id, + const TQString &text, + const TQString &details, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * Like detailedError + * + * This function will return immediately, the messagebox will be shown + * once the application enters an event loop and no other messagebox + * is being shown. + * + * Note that if the parent gets deleted, the messagebox will not be + * shown. + */ + static void queuedDetailedError( TQWidget *parent, + const TQString &text, + const TQString &details, + const TQString &caption = TQString::null); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void queuedDetailedErrorWId( WId parent_id, + const TQString &text, + const TQString &details, + const TQString &caption = TQString::null); + + /** + * Display an "Sorry" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Sorry"). + * @param options see OptionsType + * + * Either your program messed up and asks for understanding + * or your user did something stupid. + * + * To be used for small problems like + * "Sorry, I can't find the file you specified." + * + * The default button is "&OK". Pressing "Esc" selects the OK-button. + * + * NOTE: The ok button will always have the i18n'ed text '&OK'. + */ + + static void sorry(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void sorryWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * Displays a "Sorry" dialog with a "Details >>" button. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param details Detailed message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Sorry"). + * @param options see OptionsType + * + * Either your program messed up and asks for understanding + * or your user did something stupid. + * + * To be used for small problems like + * "Sorry, I can't find the file you specified." + * + * And then @p details can contain something like + * "foobar.txt was not found in any of + * the following directories: + * /usr/bin,/usr/local/bin,/usr/sbin" + * + * The default button is "&OK". Pressing "Esc" selects the OK-button. + * + * NOTE: The ok button will always have the i18n'ed text '&OK'. + */ + + static void detailedSorry(TQWidget *parent, + const TQString &text, + const TQString &details, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void detailedSorryWId(WId parent_id, + const TQString &text, + const TQString &details, + const TQString &caption = TQString::null, + int options = Notify); + + /** + * Display an "Information" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Information"). + * @param dontShowAgainName If provided, a checkbox is added with which + * further notifications can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * @param options see OptionsType + * + * + * Your program wants to tell the user something. + * To be used for things like: + * "Your bookmarks have been rearranged." + * + * The default button is "&OK". Pressing "Esc" selects the OK-button. + * + * NOTE: The OK button will always have the i18n'ed text '&OK'. + */ + + static void information(TQWidget *parent, + const TQString &text, + const TQString &caption = TQString::null, + const TQString &dontShowAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void informationWId(WId parent_id, + const TQString &text, + const TQString &caption = TQString::null, + const TQString &dontShowAgainName = TQString::null, + int options = Notify); + + /** + * Display an "Information" dialog with a listbox. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. If the + * list is empty, it doesn't show any listbox, working + * as information. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("Information"). + * @param dontShowAgainName If provided, a checkbox is added with which + * further notifications can be turned off. + * The string is used to lookup and store the setting + * in the applications config file. + * The setting is stored in the "Notification Messages" group. + * @param options see OptionsType + * + * + * Your program wants to tell the user something. + * To be used for things like: + * "The following bookmarks have been rearranged:" + * + * The default button is "&OK". Pressing "Esc" selects the OK-button. + * + * NOTE: The OK button will always have the i18n'ed text '&OK'. + * @since 3.1 + */ + + static void informationList(TQWidget *parent, + const TQString &text, + const TQStringList & strlist, + const TQString &caption = TQString::null, + const TQString &dontShowAgainName = TQString::null, + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void informationListWId(WId parent_id, + const TQString &text, + const TQStringList & strlist, + const TQString &caption = TQString::null, + const TQString &dontShowAgainName = TQString::null, + int options = Notify); + + /** + * Enable all messages which have been turned off with the + * @p dontShowAgainName feature. + */ + static void enableAllMessages(); + + /** + * Re-enable a specific @p dontShowAgainName messages that had + * previously been turned off. + * @see saveDontShowAgainYesNo() + * @see saveDontShowAgainContinue() + * @since 3.2 + */ + static void enableMessage(const TQString &dontShowAgainName); + + /** + * Display an "About" dialog. + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param text Message string. + * @param caption Message box title. The application name is added to + * the title. The default title is i18n("About \<appname\>"). + * @param options see OptionsType + * + * + * Your program wants to show some general information about the application + * like the authors's names and email addresses. + * + * The default button is "&OK". + * + * NOTE: The ok button will always have the i18n'ed text '&OK'. + */ + static void about(TQWidget *parent, + const TQString& text, + const TQString& caption = TQString::null, + int options = Notify); + + /** + * Alternate method to show a messagebox: + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param type type of message box: QuestionYesNo, WarningYesNo, WarningContinueCancel... + * @param text Message string. + * @param caption Message box title. + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param dontShowAskAgainName If provided, a checkbox is added with which + * further questions/informations can be turned off. If turned off + * all questions will be automatically answered with the + * last answer (either Yes or No), if the message box needs an answer. + * The string is used to lookup and store the setting + * in the applications config file. + * @param options see OptionsType + * Note: for ContinueCancel, buttonYes is the continue button and buttonNo is unused. + * and for Information, none is used. + * @return a button code, as defined in KMessageBox. + */ + static int messageBox( TQWidget *parent, DialogType type, const TQString &text, + const TQString &caption, + const KGuiItem &buttonYes, + const KGuiItem &buttonNo, + const TQString &dontShowAskAgainName, + int options = Notify); + + /** + * Alternate method to show a messagebox: + * + * @param parent If @p parent is 0, then the message box becomes an + * application-global modal dialog box. If @p parent is a + * widget, the message box becomes modal relative to parent. + * @param type type of message box: QuestionYesNo, WarningYesNo, WarningContinueCancel... + * @param text Message string. + * @param caption Message box title. + * @param buttonYes The text for the first button. + * The default is i18n("&Yes"). + * @param buttonNo The text for the second button. + * The default is i18n("&No"). + * @param options see OptionsType + * Note: for ContinueCancel, buttonYes is the continue button and buttonNo is unused. + * and for Information, none is used. + * @return a button code, as defined in KMessageBox. + */ + // KDE4 - merge with above? + static int messageBox( TQWidget *parent, DialogType type, const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + int options = Notify); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static int messageBoxWId( WId parent_id, DialogType type, const TQString &text, + const TQString &caption = TQString::null, + const KGuiItem &buttonYes = KStdGuiItem::yes(), + const KGuiItem &buttonNo = KStdGuiItem::no(), + const TQString &dontShowAskAgainName = TQString::null, + int options = Notify); + + /** + * Like messageBox + * + * Only for message boxes of type Information, Sorry or Error. + * + * This function will return immediately, the messagebox will be shown + * once the application enters an event loop and no other messagebox + * is being shown. + * + * Note that if the parent gets deleted, the messagebox will not be + * shown. + */ + static void queuedMessageBox( TQWidget *parent, + DialogType type, const TQString &text, + const TQString &caption, + int options ); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void queuedMessageBoxWId( WId parent_id, + DialogType type, const TQString &text, + const TQString &caption, + int options ); + + /** + * @overload + * + * This is an overloaded member function, provided for convenience. + * It behaves essentially like the above function. + */ + static void queuedMessageBox( TQWidget *parent, + DialogType type, const TQString &text, + const TQString &caption = TQString::null ); + + /** + * This function accepts the window id of the parent window, instead + * of TQWidget*. It should be used only when necessary. + * @since 3.2 + */ + static void queuedMessageBoxWId( WId parent_id, + DialogType type, const TQString &text, + const TQString &caption = TQString::null ); + + /** + * @return true if the corresponding yes/no message box should be shown. + * @param dontShowAgainName the name that identify the message box. If + * empty, true is always returned. + * @param result is set to the result (Yes or No) that was chosen the last + * time the message box was shown. Only meaningful, if the message box + * should not be shown. + * @since 3.2 + */ + static bool shouldBeShownYesNo(const TQString &dontShowAgainName, + ButtonCode &result); + /** + * @return true if the corresponding continue/cancel message box should be + * shown. + * @param dontShowAgainName the name that identify the message box. If + * empty, true is always returned. + * @since 3.2 + */ + static bool shouldBeShownContinue(const TQString &dontShowAgainName); + + /** + * Save the fact that the yes/no message box should not be shown again. + * @param dontShowAgainName the name that identify the message box. If + * empty, this method does nothing. + * @param result the value (Yes or No) that should be used as the result + * for the message box. + * @since 3.2 + */ + static void saveDontShowAgainYesNo(const TQString &dontShowAgainName, + ButtonCode result); + + /** + * Save the fact that the continue/cancel message box should not be shown + * again. + * @param dontShowAgainName the name that identify the message box. If + * empty, this method does nothing. + * @since 3.2 + */ + static void saveDontShowAgainContinue(const TQString &dontShowAgainName); + + /** + * Use @p cfg for all settings related to the dontShowAgainName feature. + * If @p cfg is 0 (default) KGlobal::config() will be used. + * @since 3.2 + */ + static void setDontShowAskAgainConfig(KConfig* cfg); + + /** + * Create content and layout of a standard dialog + * + * @param dialog The parent dialog base + * @param icon Which predefined icon the message box shall show. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. + * If the list is empty, it doesn't show any listbox + * @param ask The text of the checkbox. If empty none will be shown. + * @param checkboxReturn The result of the checkbox. If it's initially + * true then the checkbox will be checked by default. + * @param options see OptionsType + * @param details Detailed message string. + * @since 3.3 + * @return A KDialogBase button code, not a KMessageBox button code, + * based on the buttonmask given to the constructor of the + * @p dialog (ie. will return KDialogBase::Yes [256] instead of + * KMessageBox::Yes [3]). Will return KMessageBox::Cancel + * if the message box is queued for display instead of + * exec()ed immediately or if the option NoExec is set. + * @note The @p dialog that is passed in is deleted by this + * function. Do not delete it yourself. + */ + static int createKMessageBox(KDialogBase *dialog, TQMessageBox::Icon icon, + const TQString &text, const TQStringList &strlist, + const TQString &ask, bool *checkboxReturn, + int options, const TQString &details=TQString::null); + + /** + * Create content and layout of a standard dialog + * + * @param dialog The parent dialog base + * @param icon A TQPixmap containing the icon to be displayed in the + * dialog next to the text. + * @param text Message string. + * @param strlist List of strings to be written in the listbox. + * If the list is empty, it doesn't show any listbox + * @param ask The text of the checkbox. If empty none will be shown. + * @param checkboxReturn The result of the checkbox. If it's initially + * true then the checkbox will be checked by default. + * @param options see OptionsType + * @param details Detailed message string. + * @param notifyType The type of notification to send when this message + * is presentend. + * @since 3.3 + * @return A KDialogBase button code, not a KMessageBox button code, + * based on the buttonmask given to the constructor of the + * @p dialog (ie. will return KDialogBase::Yes [256] instead of + * KMessageBox::Yes [3]). Will return KMessageBox::Cancel + * if the message box is queued for display instead of + * exec()ed immediately or if the option NoExec is set. + * @note The @p dialog that is passed in is deleted by this + * function. Do not delete it yourself. + */ + static int createKMessageBox(KDialogBase *dialog, TQPixmap icon, + const TQString &text, const TQStringList &strlist, + const TQString &ask, bool *checkboxReturn, + int options, const TQString &details=TQString::null, + TQMessageBox::Icon notifyType=TQMessageBox::Information); + +private: + static KConfig* againConfig; +}; + +#endif |