KDb

KDbMessageHandler.h
1 /* This file is part of the KDE project
2  Copyright (C) 2004-2015 JarosÅ‚aw Staniek <[email protected]>
3 
4  Contains parts of kmessagebox.h
5  Copyright (C) 1999 Waldo Bastian ([email protected])
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 
33 class KDbResult;
34 class KDbResultable;
35 class KDbMessageHandler;
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 */
65 class KDB_EXPORT KDbMessageGuard
66 {
67 public:
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 
80  ~KDbMessageGuard();
81 
82 protected:
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 */
96 class KDB_EXPORT KDbMessageTitleSetter
97 {
98 public:
99  explicit KDbMessageTitleSetter(KDbResult* result, const QString& message = QString());
100  explicit KDbMessageTitleSetter(KDbResultable* resultable, const QString& message = QString());
102 
103 protected:
104  KDbResult* m_result;
105  QString m_prevMsgTitle;
106 private:
107  Q_DISABLE_COPY(KDbMessageTitleSetter)
108 };
109 
110 //! An abstract class used to specify GUI information such as button texts tooltips and icons.
111 class KDbGuiItem : private QHash<QByteArray, QVariant>
112 {
113 public:
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(); }
125 private:
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 */
134 class KDB_EXPORT KDbMessageHandler
135 {
136 public:
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
168  enum Option
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(
197  KDbMessageHandler::MessageType messageType,
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 = nullptr,
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 
238 protected:
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;
245 private:
246  Q_DISABLE_COPY(KDbMessageHandler)
247 };
248 
249 #endif
QuestionType
Question types.
An abstract class used to specify GUI information such as button texts tooltips and icons.
const T value(const Key &key) const const
ButtonCode
Button codes.
QList< Key > keys() const const
void clear()
QHash::iterator insert(const Key &key, const T &value)
Interface for classes providing a result.
Option
Message options.
int remove(const Key &key)
bool isEmpty() const const
MessageType
Message types.
A guard class for transmitting messages based on KDbResult.
bool contains(const Key &key) const const
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Fri Aug 12 2022 04:06:23 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.