0031189: Draw Harness, ViewerTest - send messages to Message::DefaultMessenger()
[occt.git] / src / Message / Message_Messenger.hxx
CommitLineData
42cf5bc1 1// Created on: 2007-06-28
2// Created by: OCC Team
3// Copyright (c) 2007-2014 OPEN CASCADE SAS
4//
5// This file is part of Open CASCADE Technology software library.
6//
7// This library is free software; you can redistribute it and/or modify it under
8// the terms of the GNU Lesser General Public License version 2.1 as published
9// by the Free Software Foundation, with special exception defined in the file
10// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11// distribution for complete text of the license and disclaimer of any warranty.
12//
13// Alternatively, this file may be used under the terms of Open CASCADE
14// commercial license or contractual agreement.
15
16#ifndef _Message_Messenger_HeaderFile
17#define _Message_Messenger_HeaderFile
18
983fd6c0 19#include <Message_Gravity.hxx>
42cf5bc1 20#include <Message_SequenceOfPrinters.hxx>
23fe70ec 21
983fd6c0 22#include <TCollection_HAsciiString.hxx>
23#include <TCollection_HExtendedString.hxx>
24
42cf5bc1 25class Message_Printer;
42cf5bc1 26
9fd2d2c3 27// resolve name collisions with WinAPI headers
28#ifdef AddPrinter
29 #undef AddPrinter
30#endif
42cf5bc1 31
32class Message_Messenger;
25e59720 33DEFINE_STANDARD_HANDLE(Message_Messenger, Standard_Transient)
42cf5bc1 34
35//! Messenger is API class providing general-purpose interface for
36//! libraries that may issue text messages without knowledge
37//! of how these messages will be further processed.
38//!
39//! The messenger contains a sequence of "printers" which can be
40//! customized by the application, and dispatches every received
41//! message to all the printers.
42//!
23fe70ec 43//! For convenience, a set of methods Send...() returning a string
44//! stream buffer is defined for use of stream-like syntax with operator <<
45//!
46//! Example:
47//! ~~~~~
48//! Messenger->SendFail() << " Unknown fail at line " << aLineNo << " in file " << aFile;
49//! ~~~~~
50//!
51//! The message is sent to messenger on destruction of the stream buffer,
52//! call to Flush(), or passing manipulator std::ends, std::endl, or std::flush.
53//! Empty messages are not sent except if manipulator is used.
25e59720 54class Message_Messenger : public Standard_Transient
42cf5bc1 55{
983fd6c0 56 DEFINE_STANDARD_RTTIEXT(Message_Messenger, Standard_Transient)
42cf5bc1 57public:
23fe70ec 58 //! Auxiliary class wrapping std::stringstream thus allowing constructing
59 //! message via stream interface, and putting result into its creator
60 //! Message_Messenger within destructor.
61 //!
62 //! It is intended to be used either as temporary object or as local
63 //! variable, note that content will be lost if it is copied.
64 class StreamBuffer
65 {
66 public:
67
68 //! Destructor flushing constructed message.
69 ~StreamBuffer() { Flush(); }
70
71 //! Flush collected string to messenger
72 void Flush(Standard_Boolean doForce = Standard_False)
73 {
74 myStream.flush();
75 if (doForce || myStream.rdbuf()->in_avail() > 0)
76 {
77 myMessenger->Send (myStream.str().c_str(), myGravity);
78 myStream.str(std::string()); // empty the buffer for possible reuse
79 }
80 }
81
82 //! Formal copy constructor.
83 //!
84 //! Since buffer is intended for use as temporary object or local
85 //! variable, copy (or move) is needed only formally to be able to
86 //! return the new instance from relevant creation method.
87 //! In practice it should never be called because modern compilers
88 //! create such instances in place.
89 //! However note that if this constructor is called, the buffer
90 //! content (string) will not be copied (move is not supported for
91 //! std::stringstream class on old compilers such as gcc 4.4, msvc 9).
92 StreamBuffer (const StreamBuffer& theOther)
93 : myMessenger(theOther.myMessenger), myGravity(theOther.myGravity)
94 {
95 }
96
97 //! Wrapper for operator << of the stream
98 template <typename T>
99 StreamBuffer& operator << (const T& theArg)
100 {
101 myStream << theArg;
102 return *this;
103 }
104
105 //! Operator << for manipulators of ostream (ends, endl, flush),
106 //! flushes the buffer (sends the message)
107 StreamBuffer& operator << (std::ostream& (*)(std::ostream&))
108 {
109 Flush(Standard_True);
110 return *this;
111 }
112
113 //! Access to the stream object
114 Standard_SStream& Stream () { return myStream; }
115
116 private:
117 friend class Message_Messenger;
118
119 //! Main constructor creating temporary buffer.
120 //! Accessible only to Messenger class.
121 StreamBuffer (Message_Messenger* theMessenger, Message_Gravity theGravity)
122 : myMessenger (theMessenger),
123 myGravity (theGravity)
124 {}
125
126 private:
127 Message_Messenger* myMessenger; // don't make a Handle since this object should be created on stack
128 Message_Gravity myGravity;
129 Standard_SStream myStream;
130 };
131
132public:
42cf5bc1 133
04232180 134 //! Empty constructor; initializes by single printer directed to std::cout.
42cf5bc1 135 //! Note: the default messenger is not empty but directed to cout
136 //! in order to protect against possibility to forget defining printers.
137 //! If printing to cout is not needed, clear messenger by GetPrinters().Clear()
138 Standard_EXPORT Message_Messenger();
139
140 //! Create messenger with single printer
141 Standard_EXPORT Message_Messenger(const Handle(Message_Printer)& thePrinter);
142
143 //! Add a printer to the messenger.
144 //! The printer will be added only if it is not yet in the list.
145 //! Returns True if printer has been added.
146 Standard_EXPORT Standard_Boolean AddPrinter (const Handle(Message_Printer)& thePrinter);
147
148 //! Removes specified printer from the messenger.
149 //! Returns True if this printer has been found in the list
150 //! and removed.
151 Standard_EXPORT Standard_Boolean RemovePrinter (const Handle(Message_Printer)& thePrinter);
152
153 //! Removes printers of specified type (including derived classes)
154 //! from the messenger.
155 //! Returns number of removed printers.
156 Standard_EXPORT Standard_Integer RemovePrinters (const Handle(Standard_Type)& theType);
157
158 //! Returns current sequence of printers
983fd6c0 159 const Message_SequenceOfPrinters& Printers() const { return myPrinters; }
160
42cf5bc1 161 //! Returns sequence of printers
162 //! The sequence can be modified.
983fd6c0 163 Message_SequenceOfPrinters& ChangePrinters() { return myPrinters; }
164
42cf5bc1 165 //! Dispatch a message to all the printers in the list.
166 //! Three versions of string representations are accepted for
167 //! convenience, by default all are converted to ExtendedString.
168 //! The parameter putEndl specifies whether the new line should
169 //! be started after this message (default) or not (may have
170 //! sense in some conditions).
23fe70ec 171 Standard_EXPORT void Send (const Standard_CString theString,
172 const Message_Gravity theGravity = Message_Warning,
173 const Standard_Boolean putEndl = Standard_True) const;
42cf5bc1 174
175 //! See above
23fe70ec 176 Standard_EXPORT void Send (const TCollection_AsciiString& theString,
177 const Message_Gravity theGravity = Message_Warning,
178 const Standard_Boolean putEndl = Standard_True) const;
42cf5bc1 179
180 //! See above
23fe70ec 181 Standard_EXPORT void Send (const TCollection_ExtendedString& theString,
182 const Message_Gravity theGravity = Message_Warning,
183 const Standard_Boolean putEndl = Standard_True) const;
184
185 //! Create string buffer for message of specified type
186 StreamBuffer Send (Message_Gravity theGravity) { return StreamBuffer (this, theGravity); }
187
188 //! Create string buffer for sending Fail message
189 StreamBuffer SendFail () { return Send (Message_Fail); }
190
191 //! Create string buffer for sending Alarm message
192 StreamBuffer SendAlarm () { return Send (Message_Alarm); }
193
194 //! Create string buffer for sending Warning message
195 StreamBuffer SendWarning () { return Send (Message_Warning); }
196
197 //! Create string buffer for sending Info message
198 StreamBuffer SendInfo () { return Send (Message_Info); }
199
200 //! Create string buffer for sending Trace message
201 StreamBuffer SendTrace () { return Send (Message_Trace); }
202
203 //! Short-cut to Send (theMessage, Message_Fail)
204 void SendFail (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Fail); }
205
206 //! Short-cut to Send (theMessage, Message_Alarm)
207 void SendAlarm (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Alarm); }
208
209 //! Short-cut to Send (theMessage, Message_Warning)
210 void SendWarning (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Warning); }
211
212 //! Short-cut to Send (theMessage, Message_Info)
213 void SendInfo (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Info); }
214
215 //! Short-cut to Send (theMessage, Message_Trace)
216 void SendTrace (const TCollection_AsciiString& theMessage) { Send (theMessage, Message_Trace); }
42cf5bc1 217
42cf5bc1 218private:
219
42cf5bc1 220 Message_SequenceOfPrinters myPrinters;
221
42cf5bc1 222};
223
983fd6c0 224// CString
225inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
226 const Standard_CString theStr)
227{
228 theMessenger->Send (theStr, Message_Info, Standard_False);
229 return theMessenger;
230}
231
232// AsciiString
233inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
234 const TCollection_AsciiString& theStr)
235{
236 theMessenger->Send (theStr, Message_Info, Standard_False);
237 return theMessenger;
238}
42cf5bc1 239
983fd6c0 240// HAsciiString
241inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
242 const Handle(TCollection_HAsciiString)& theStr)
243{
244 theMessenger->Send (theStr->String(), Message_Info, Standard_False);
245 return theMessenger;
246}
42cf5bc1 247
983fd6c0 248// ExtendedString
249inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
250 const TCollection_ExtendedString& theStr)
251{
252 theMessenger->Send (theStr, Message_Info, Standard_False);
253 return theMessenger;
254}
42cf5bc1 255
983fd6c0 256// HExtendedString
257inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
258 const Handle(TCollection_HExtendedString)& theStr)
259{
260 theMessenger->Send (theStr->String(), Message_Info, Standard_False);
261 return theMessenger;
262}
42cf5bc1 263
983fd6c0 264// Integer
265inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
266 const Standard_Integer theVal)
267{
268 TCollection_AsciiString aStr (theVal);
269 theMessenger->Send (aStr, Message_Info, Standard_False);
270 return theMessenger;
271}
272
273// Real
274inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
275 const Standard_Real theVal)
276{
277 TCollection_AsciiString aStr (theVal);
278 theMessenger->Send (aStr, Message_Info, Standard_False);
279 return theMessenger;
280}
281
282// Stream
283inline const Handle(Message_Messenger)& operator<< (const Handle(Message_Messenger)& theMessenger,
284 const Standard_SStream& theStream)
285{
286 theMessenger->Send (theStream.str().c_str(), Message_Info, Standard_False);
287 return theMessenger;
288}
289
290// manipulators
291inline const Handle(Message_Messenger)&
292 operator << (const Handle(Message_Messenger)& theMessenger,
293 const Handle(Message_Messenger)& (*pman) (const Handle(Message_Messenger)&))
294{
295 return pman (theMessenger);
296}
42cf5bc1 297
04232180 298// Message_EndLine
299inline const Handle(Message_Messenger)& Message_EndLine (const Handle(Message_Messenger)& theMessenger)
300{
301 theMessenger->Send ("", Message_Info, Standard_True);
302 return theMessenger;
303}
304
42cf5bc1 305#endif // _Message_Messenger_HeaderFile