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
26class 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 */
49namespace 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 */
113class KDECORE_EXPORT KMessageHandler
114{
115public:
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