File indexing completed on 2024-11-10 04:15:54
0001 /* This file is part of the KDE project 0002 Copyright (C) 2004-2015 Jarosław Staniek <staniek@kde.org> 0003 0004 Contains parts of kmessagebox.h 0005 Copyright (C) 1999 Waldo Bastian (bastian@kde.org) 0006 0007 This library is free software; you can redistribute it and/or 0008 modify it under the terms of the GNU Library General Public 0009 License as published by the Free Software Foundation; either 0010 version 2 of the License, or (at your option) any later version. 0011 0012 This library is distributed in the hope that it will be useful, 0013 but WITHOUT ANY WARRANTY; without even the implied warranty of 0014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0015 Library General Public License for more details. 0016 0017 You should have received a copy of the GNU Library General Public License 0018 along with this library; see the file COPYING.LIB. If not, write to 0019 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0020 * Boston, MA 02110-1301, USA. 0021 */ 0022 0023 #ifndef KDB_MSGHANDLER_H 0024 #define KDB_MSGHANDLER_H 0025 0026 #include <QPointer> 0027 #include <QHash> 0028 #include <QVariant> 0029 #include <QWidget> 0030 0031 #include "kdb_export.h" 0032 0033 class KDbResult; 0034 class KDbResultable; 0035 class KDbMessageHandler; 0036 0037 //! A guard class for transmitting messages based on KDbResult 0038 /*! It's intended use is for top-level public methods in applications that have to display 0039 messages. Create it's instance on stack; at the end of the block, on KDbMessageGuard's 0040 destruction result will be checked. If it's not empty, error is passed to the associated 0041 message handler. 0042 The example below emits error message if result is not empty before . 0043 @code 0044 class MyClass : ... public KDbResultable { 0045 [..] 0046 MyClass(KDbMessageHandler *handler) { 0047 setMessageHandler(handler); // need ... 0048 } 0049 bool connectToProject() { 0050 KDbMessageGuard mg(this); // MyClass is KDbResultable so this easy notation is possible 0051 if (... something failed ...) { 0052 m_result = KDbResult(tr("Operation failed.")); 0053 return false; // ~KDbMessageGuard called here, m_result is passed to messageHandler() 0054 } 0055 // ... 0056 return true; // ~KDbMessageGuard called here is a no-op because there's no error in m_result 0057 } 0058 }; 0059 @endcode 0060 There are two equivalent variants of usage: 0061 - using the KDbResultable object as in the example above (recommended) 0062 - using a reference to a KDbResult and a KDbMessageHandler 0063 @note instantiating KDbMessageGuard objects on the heap makes not much sense. 0064 */ 0065 class KDB_EXPORT KDbMessageGuard 0066 { 0067 public: 0068 //! Builds a guard in the current code block using @a resultable 0069 //! Infromation from @a resultable will be used in ~KDbMessageGuard() to pass message 0070 //! to the resultable->messageHandler() handler if the handler is present 0071 //! and resultable->result().isError() == true. 0072 //! @note @a resultable is required 0073 explicit KDbMessageGuard(KDbResultable *resultable); 0074 0075 //! Builds a guard in the current code block using a reference to @a result and @a handler 0076 //! These will be used in ~KDbMessageGuard() is result.isError() == true. 0077 //! @note @a handler is required 0078 KDbMessageGuard(const KDbResult &result, KDbMessageHandler *handler); 0079 0080 ~KDbMessageGuard(); 0081 0082 protected: 0083 Q_DISABLE_COPY(KDbMessageGuard) 0084 class Private; 0085 Private * const d; 0086 }; 0087 0088 /*! Helper for setting temporary message title for an KDbResult object. 0089 Message title is a text prepended to error or warning messages. 0090 Use it as follows: 0091 @code 0092 KDbMessageTitleSetter ts(&m_result, tr("Terrible error occurred")); 0093 @endcode 0094 After leaving the current code block, myResultableObject's message title will be set back to the previous value. 0095 */ 0096 class KDB_EXPORT KDbMessageTitleSetter 0097 { 0098 public: 0099 explicit KDbMessageTitleSetter(KDbResult* result, const QString& message = QString()); 0100 explicit KDbMessageTitleSetter(KDbResultable* resultable, const QString& message = QString()); 0101 ~KDbMessageTitleSetter(); 0102 0103 protected: 0104 KDbResult* m_result; 0105 QString m_prevMsgTitle; 0106 private: 0107 Q_DISABLE_COPY(KDbMessageTitleSetter) 0108 }; 0109 0110 //! An abstract class used to specify GUI information such as button texts tooltips and icons. 0111 class KDbGuiItem : private QHash<QByteArray, QVariant> 0112 { 0113 public: 0114 KDbGuiItem(); 0115 ~KDbGuiItem(); 0116 inline KDbGuiItem& setProperty(const QByteArray& name, const QVariant& value) 0117 { insert(name, value); return *this; } 0118 void removeProperty(const QByteArray& name) { remove(name); } 0119 inline bool isEmpty() const { return QHash<QByteArray, QVariant>::isEmpty(); } 0120 inline QVariant property(const QByteArray& name, const QVariant& defaultValue = QVariant()) const 0121 { return value(name, defaultValue); } 0122 inline bool hasProperty(const QByteArray& name) const { return contains(name); } 0123 inline QList<QByteArray> propertyNames() const { return keys(); } 0124 inline void clear() { QHash<QByteArray, QVariant>::clear(); } 0125 private: 0126 class Private; 0127 Private * const d; 0128 Q_DISABLE_COPY(KDbGuiItem) 0129 }; 0130 0131 /*! A prototype for Message Handler usable 0132 for reacting on messages sent by KDbObject object(s). 0133 */ 0134 class KDB_EXPORT KDbMessageHandler 0135 { 0136 public: 0137 //! Message types 0138 enum MessageType 0139 { 0140 Information = 1, 0141 Error = 2, 0142 Warning = 3, 0143 Sorry = 4, 0144 Fatal = 5 0145 }; 0146 0147 //! Question types 0148 enum QuestionType 0149 { 0150 QuestionYesNo = 1, 0151 QuestionYesNoCancel = 2, 0152 WarningYesNo = 3, 0153 WarningContinueCancel = 4, 0154 WarningYesNoCancel = 5 0155 }; 0156 0157 //! Button codes 0158 enum ButtonCode 0159 { 0160 Ok = 1, 0161 Cancel = 2, 0162 Yes = Ok, 0163 No = 3, 0164 Continue = 4 0165 }; 0166 0167 //! Message options 0168 enum Option 0169 { 0170 Notify = 1, ///< Emit a KNotify event 0171 AllowLink = 2, ///< The message may contain links. 0172 Dangerous = 4 ///< The action to be confirmed by the dialog is a potentially destructive one 0173 }; 0174 Q_DECLARE_FLAGS(Options, Option) 0175 0176 /*! Constructs message handler, @a parent is a widget that will be a parent 0177 for displaying gui elements (e.g. message boxes). Can be 0 for non-gui usage. */ 0178 explicit KDbMessageHandler(QWidget *parent = nullptr); 0179 0180 virtual ~KDbMessageHandler(); 0181 0182 /*! @return true if the handler is enables so messages are not blocked. 0183 @see setEnabled(bool) */ 0184 bool messagesEnabled() const; 0185 0186 /*! Enables or disabled the handler to block/unblock its messages. 0187 Sometimes both lower- and higher-level messages are received, 0188 what is not optimal as only one of them should be displayed (e.g. a higher level 0189 with details). This can be solved by calling setEnabled(false) shortly before 0190 an action that can send the unwanted message. Afterwards messages can be enabled again 0191 by calling setEnabled(true). 0192 By default messages are enabled. */ 0193 void setMessagesEnabled(bool enable); 0194 0195 /*! Shows error message with @a title (it is not caption) and details. */ 0196 virtual void showErrorMessage( 0197 KDbMessageHandler::MessageType messageType, 0198 const QString &message, 0199 const QString &details = QString(), 0200 const QString &caption = QString() 0201 ) = 0; 0202 0203 /*! Shows error message with @a message text. Existing error message from @a obj object 0204 is also copied, if present. */ 0205 virtual void showErrorMessage( 0206 const KDbResult& result, 0207 KDbMessageHandler::MessageType messageType = Error, 0208 const QString& message = QString(), 0209 const QString& caption = QString() 0210 ) = 0; 0211 0212 /*! Interactively asks a question. For GUI version, message boxes are used. 0213 @a defaultResult is returned in case when no message handler is installed. 0214 @a message should contain translated string. 0215 Value of ButtonCode is returned. 0216 Reimplement this. This implementation does nothing, just returns @a defaultResult. */ 0217 virtual KDbMessageHandler::ButtonCode askQuestion( 0218 KDbMessageHandler::QuestionType messageType, 0219 const QString& message, 0220 const QString &caption = QString(), 0221 KDbMessageHandler::ButtonCode defaultResult = KDbMessageHandler::Yes, 0222 const KDbGuiItem &buttonYes = KDbGuiItem(), 0223 const KDbGuiItem &buttonNo = KDbGuiItem(), 0224 const QString &dontShowAskAgainName = QString(), 0225 KDbMessageHandler::Options options = {}, 0226 KDbMessageHandler* msgHandler = nullptr); 0227 0228 //! @return message redirection for this handler or 0 if there is no redirection. 0229 KDbMessageHandler* redirection(); 0230 0231 //! @overload KDbMessageHandler* redirection() 0232 const KDbMessageHandler* redirection() const; 0233 0234 /*! Sets redirection of all messages for this handler to @a otherHandler. 0235 Passing 0 removes redirection. Setting new redirection replaces previous. */ 0236 void setRedirection(KDbMessageHandler *otherHandler); 0237 0238 protected: 0239 /*! @return a widget that will be parent for displaying gui elements (e.g. message boxes). 0240 Can be 0 for non-gui cases. */ 0241 QWidget *parentWidget(); 0242 0243 class Private; 0244 Private * const d; 0245 private: 0246 Q_DISABLE_COPY(KDbMessageHandler) 0247 }; 0248 0249 #endif