KDb

KDbMessageHandler.h
1/* This file is part of the KDE project
2 Copyright (C) 2004-2015 Jarosław Staniek <staniek@kde.org>
3
4 Contains parts of kmessagebox.h
5 Copyright (C) 1999 Waldo Bastian (bastian@kde.org)
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21*/
22
23#ifndef KDB_MSGHANDLER_H
24#define KDB_MSGHANDLER_H
25
26#include <QPointer>
27#include <QHash>
28#include <QVariant>
29#include <QWidget>
30
31#include "kdb_export.h"
32
33class KDbResult;
34class KDbResultable;
36
37//! A guard class for transmitting messages based on KDbResult
38/*! It's intended use is for top-level public methods in applications that have to display
39 messages. Create it's instance on stack; at the end of the block, on KDbMessageGuard's
40 destruction result will be checked. If it's not empty, error is passed to the associated
41 message handler.
42 The example below emits error message if result is not empty before .
43 @code
44 class MyClass : ... public KDbResultable {
45 [..]
46 MyClass(KDbMessageHandler *handler) {
47 setMessageHandler(handler); // need ...
48 }
49 bool connectToProject() {
50 KDbMessageGuard mg(this); // MyClass is KDbResultable so this easy notation is possible
51 if (... something failed ...) {
52 m_result = KDbResult(tr("Operation failed."));
53 return false; // ~KDbMessageGuard called here, m_result is passed to messageHandler()
54 }
55 // ...
56 return true; // ~KDbMessageGuard called here is a no-op because there's no error in m_result
57 }
58 };
59 @endcode
60 There are two equivalent variants of usage:
61 - using the KDbResultable object as in the example above (recommended)
62 - using a reference to a KDbResult and a KDbMessageHandler
63 @note instantiating KDbMessageGuard objects on the heap makes not much sense.
64*/
65class KDB_EXPORT KDbMessageGuard
66{
67public:
68 //! Builds a guard in the current code block using @a resultable
69 //! Infromation from @a resultable will be used in ~KDbMessageGuard() to pass message
70 //! to the resultable->messageHandler() handler if the handler is present
71 //! and resultable->result().isError() == true.
72 //! @note @a resultable is required
73 explicit KDbMessageGuard(KDbResultable *resultable);
74
75 //! Builds a guard in the current code block using a reference to @a result and @a handler
76 //! These will be used in ~KDbMessageGuard() is result.isError() == true.
77 //! @note @a handler is required
78 KDbMessageGuard(const KDbResult &result, KDbMessageHandler *handler);
79
81
82protected:
83 Q_DISABLE_COPY(KDbMessageGuard)
84 class Private;
85 Private * const d;
86};
87
88/*! Helper for setting temporary message title for an KDbResult object.
89 Message title is a text prepended to error or warning messages.
90 Use it as follows:
91 @code
92 KDbMessageTitleSetter ts(&m_result, tr("Terrible error occurred"));
93 @endcode
94 After leaving the current code block, myResultableObject's message title will be set back to the previous value.
95*/
96class KDB_EXPORT KDbMessageTitleSetter
97{
98public:
99 explicit KDbMessageTitleSetter(KDbResult* result, const QString& message = QString());
100 explicit KDbMessageTitleSetter(KDbResultable* resultable, const QString& message = QString());
102
103protected:
104 KDbResult* m_result;
105 QString m_prevMsgTitle;
106private:
107 Q_DISABLE_COPY(KDbMessageTitleSetter)
108};
109
110//! An abstract class used to specify GUI information such as button texts tooltips and icons.
111class KDbGuiItem : private QHash<QByteArray, QVariant>
112{
113public:
114 KDbGuiItem();
115 ~KDbGuiItem();
116 inline KDbGuiItem& setProperty(const QByteArray& name, const QVariant& value)
117 { insert(name, value); return *this; }
118 void removeProperty(const QByteArray& name) { remove(name); }
119 inline bool isEmpty() const { return QHash<QByteArray, QVariant>::isEmpty(); }
120 inline QVariant property(const QByteArray& name, const QVariant& defaultValue = QVariant()) const
121 { return value(name, defaultValue); }
122 inline bool hasProperty(const QByteArray& name) const { return contains(name); }
123 inline QList<QByteArray> propertyNames() const { return keys(); }
124 inline void clear() { QHash<QByteArray, QVariant>::clear(); }
125private:
126 class Private;
127 Private * const d;
128 Q_DISABLE_COPY(KDbGuiItem)
129};
130
131/*! A prototype for Message Handler usable
132 for reacting on messages sent by KDbObject object(s).
133*/
134class KDB_EXPORT KDbMessageHandler
135{
136public:
137 //! Message types
139 {
140 Information = 1,
141 Error = 2,
142 Warning = 3,
143 Sorry = 4,
144 Fatal = 5
145 };
146
147 //! Question types
149 {
150 QuestionYesNo = 1,
151 QuestionYesNoCancel = 2,
152 WarningYesNo = 3,
153 WarningContinueCancel = 4,
154 WarningYesNoCancel = 5
155 };
156
157 //! Button codes
159 {
160 Ok = 1,
161 Cancel = 2,
162 Yes = Ok,
163 No = 3,
164 Continue = 4
165 };
166
167 //! Message options
169 {
170 Notify = 1, ///< Emit a KNotify event
171 AllowLink = 2, ///< The message may contain links.
172 Dangerous = 4 ///< The action to be confirmed by the dialog is a potentially destructive one
173 };
174 Q_DECLARE_FLAGS(Options, Option)
175
176 /*! Constructs message handler, @a parent is a widget that will be a parent
177 for displaying gui elements (e.g. message boxes). Can be 0 for non-gui usage. */
178 explicit KDbMessageHandler(QWidget *parent = nullptr);
179
180 virtual ~KDbMessageHandler();
181
182 /*! @return true if the handler is enables so messages are not blocked.
183 @see setEnabled(bool) */
184 bool messagesEnabled() const;
185
186 /*! Enables or disabled the handler to block/unblock its messages.
187 Sometimes both lower- and higher-level messages are received,
188 what is not optimal as only one of them should be displayed (e.g. a higher level
189 with details). This can be solved by calling setEnabled(false) shortly before
190 an action that can send the unwanted message. Afterwards messages can be enabled again
191 by calling setEnabled(true).
192 By default messages are enabled. */
193 void setMessagesEnabled(bool enable);
194
195 /*! Shows error message with @a title (it is not caption) and details. */
196 virtual void showErrorMessage(
198 const QString &message,
199 const QString &details = QString(),
200 const QString &caption = QString()
201 ) = 0;
202
203 /*! Shows error message with @a message text. Existing error message from @a obj object
204 is also copied, if present. */
205 virtual void showErrorMessage(
206 const KDbResult& result,
207 KDbMessageHandler::MessageType messageType = Error,
208 const QString& message = QString(),
209 const QString& caption = QString()
210 ) = 0;
211
212 /*! Interactively asks a question. For GUI version, message boxes are used.
213 @a defaultResult is returned in case when no message handler is installed.
214 @a message should contain translated string.
215 Value of ButtonCode is returned.
216 Reimplement this. This implementation does nothing, just returns @a defaultResult. */
217 virtual KDbMessageHandler::ButtonCode askQuestion(
219 const QString& message,
220 const QString &caption = QString(),
221 KDbMessageHandler::ButtonCode defaultResult = KDbMessageHandler::Yes,
222 const KDbGuiItem &buttonYes = KDbGuiItem(),
223 const KDbGuiItem &buttonNo = KDbGuiItem(),
224 const QString &dontShowAskAgainName = QString(),
225 KDbMessageHandler::Options options = {},
226 KDbMessageHandler* msgHandler = nullptr);
227
228 //! @return message redirection for this handler or 0 if there is no redirection.
229 KDbMessageHandler* redirection();
230
231 //! @overload KDbMessageHandler* redirection()
232 const KDbMessageHandler* redirection() const;
233
234 /*! Sets redirection of all messages for this handler to @a otherHandler.
235 Passing 0 removes redirection. Setting new redirection replaces previous. */
236 void setRedirection(KDbMessageHandler *otherHandler);
237
238protected:
239 /*! @return a widget that will be parent for displaying gui elements (e.g. message boxes).
240 Can be 0 for non-gui cases. */
241 QWidget *parentWidget();
242
243 class Private;
244 Private * const d;
245private:
246 Q_DISABLE_COPY(KDbMessageHandler)
247};
248
249#endif
An abstract class used to specify GUI information such as button texts tooltips and icons.
A guard class for transmitting messages based on KDbResult.
MessageType
Message types.
Option
Message options.
virtual void showErrorMessage(KDbMessageHandler::MessageType messageType, const QString &message, const QString &details=QString(), const QString &caption=QString())=0
QuestionType
Question types.
virtual void showErrorMessage(const KDbResult &result, KDbMessageHandler::MessageType messageType=Error, const QString &message=QString(), const QString &caption=QString())=0
Interface for classes providing a result.
void clear()
bool contains(const Key &key) const const
iterator insert(const Key &key, const T &value)
bool isEmpty() const const
QList< Key > keys() const const
bool remove(const Key &key)
T value(const Key &key) const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:38:30 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.