1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 2006 Michaël Larouche <michael.larouche@kdemail.net> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; version 2 |
7 | of the License. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | #ifndef KDECORE_KMESSAGE_H |
20 | #define KDECORE_KMESSAGE_H |
21 | |
22 | #include <kdecore_export.h> |
23 | |
24 | #include <QtCore/QString> |
25 | |
26 | class KMessageHandler; |
27 | /** |
28 | * @brief Display an informative message using a KMessageHandler. |
29 | * |
30 | * This class does not define how to display a message, it is just |
31 | * a clean interface for developers to use. |
32 | * The job is done by the current KMessageHandler set in the class. |
33 | * |
34 | * If no KMessageHandler is currently registered in KMessage, |
35 | * the message will be outputed to stderr. |
36 | * |
37 | * Use KMessage::setMessageHandler() to use a KMessageHandler. |
38 | * |
39 | * @code |
40 | * KMessage::setMessageHandler( new KMessageBoxHandler(this) ); |
41 | * // some operation |
42 | * |
43 | * KMessage::message( KMessage::Error, i18n("Could not load service. Use kbuildsycoca to fix the service database."), i18n("KService") ); |
44 | * @endcode |
45 | * |
46 | * Some KMessageHandler are already done such as KMessageBoxMessageHandler and KPassivePopupMessageHandler. |
47 | * @author Michaël Larouche <michael.larouche@kdemail.net> |
48 | */ |
49 | namespace KMessage |
50 | { |
51 | enum MessageType |
52 | { |
53 | /** |
54 | * Error message. |
55 | * Display critical information that affect the behavior of the application. |
56 | */ |
57 | Error, |
58 | /** |
59 | * Information message. |
60 | * Display useful information to the user. |
61 | */ |
62 | Information, |
63 | /** |
64 | * Warning message. |
65 | * Display a message that could affect the behavior of the application. |
66 | */ |
67 | Warning, |
68 | /** |
69 | * Sorry message. |
70 | * Display a message explaining that a task couldn't be accomplished. |
71 | */ |
72 | Sorry, |
73 | /** |
74 | * Fatal message. |
75 | * Display a message before the application fail and close itself. |
76 | */ |
77 | Fatal |
78 | }; |
79 | |
80 | /** |
81 | * @brief Display a long message of a certain type. |
82 | * A long message span on multiple lines and can have a caption. |
83 | * |
84 | * @param messageType Currrent type of message. See MessageType enum. |
85 | * @param text Long message to be displayed. |
86 | * @param caption Caption to be used. This is optional. |
87 | */ |
88 | KDECORE_EXPORT void message(KMessage::MessageType messageType, const QString &text, const QString &caption = QString()); |
89 | |
90 | /** |
91 | * @brief Set the current KMessageHandler |
92 | * Note that this method takes ownership of the KMessageHandler. |
93 | * @param handler Instance of a real KMessageHandler. |
94 | * |
95 | * @warning This function isn't thread-safe. You don't want to |
96 | * change the message handler during the program's |
97 | * execution anyways. Do so <b>only</b> at start-up. |
98 | */ |
99 | KDECORE_EXPORT void setMessageHandler(KMessageHandler *handler); |
100 | } |
101 | |
102 | /** |
103 | * \class KMessageHandler kmessage.h <KMessageHandler> |
104 | * |
105 | * @brief Abstract class for KMessage handler. |
106 | * This class define how KMessage display a message. |
107 | * |
108 | * Reimplement the virtual methods then set your custom |
109 | * KMessageHandler using KMessage::setMessageHandler() |
110 | * |
111 | * @author Michaël Larouche <michael.larouche@kdemail.net> |
112 | */ |
113 | class KDECORE_EXPORT KMessageHandler |
114 | { |
115 | public: |
116 | virtual ~KMessageHandler() {} |
117 | /** |
118 | * @brief Display a long message of a certain type. |
119 | * A long message span on multiple lines and can have a caption. |
120 | * |
121 | * @param type Currrent type of message. See MessageType enum. |
122 | * @param text Long message to be displayed. |
123 | * @param caption Caption to be used. This is optional. |
124 | */ |
125 | virtual void message(KMessage::MessageType type, const QString &text, const QString &caption) = 0; |
126 | }; |
127 | |
128 | #endif |
129 | // kate: space-indent on; indent-width 4; encoding utf-8; replace-tabs on; |
130 | |