0031189: Draw Harness, ViewerTest - send messages to Message::DefaultMessenger()
[occt.git] / src / Message / Message_Messenger.hxx
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
19 #include <Message_Gravity.hxx>
20 #include <Message_SequenceOfPrinters.hxx>
21
22 #include <TCollection_HAsciiString.hxx>
23 #include <TCollection_HExtendedString.hxx>
24
25 class Message_Printer;
26
27 // resolve name collisions with WinAPI headers
28 #ifdef AddPrinter
29   #undef AddPrinter
30 #endif
31
32 class Message_Messenger;
33 DEFINE_STANDARD_HANDLE(Message_Messenger, Standard_Transient)
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 //!
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.
54 class Message_Messenger : public Standard_Transient
55 {
56   DEFINE_STANDARD_RTTIEXT(Message_Messenger, Standard_Transient)
57 public:
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
132 public:
133
134   //! Empty constructor; initializes by single printer directed to std::cout.
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
159   const Message_SequenceOfPrinters& Printers() const { return myPrinters; }
160
161   //! Returns sequence of printers
162   //! The sequence can be modified.
163   Message_SequenceOfPrinters& ChangePrinters() { return myPrinters; }
164
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).
171   Standard_EXPORT void Send (const Standard_CString theString,
172                              const Message_Gravity theGravity = Message_Warning,
173                              const Standard_Boolean putEndl = Standard_True) const;
174   
175   //! See above
176   Standard_EXPORT void Send (const TCollection_AsciiString& theString,
177                              const Message_Gravity theGravity = Message_Warning,
178                              const Standard_Boolean putEndl = Standard_True) const;
179   
180   //! See above
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); }
217
218 private:
219
220   Message_SequenceOfPrinters myPrinters;
221
222 };
223
224 // CString
225 inline 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
233 inline 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 }
239
240 // HAsciiString
241 inline 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 }
247
248 // ExtendedString
249 inline 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 }
255
256 // HExtendedString
257 inline 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 }
263
264 // Integer
265 inline 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
274 inline 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
283 inline 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
291 inline 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 }
297
298 // Message_EndLine
299 inline const Handle(Message_Messenger)& Message_EndLine (const Handle(Message_Messenger)& theMessenger)
300 {
301   theMessenger->Send ("", Message_Info, Standard_True);
302   return theMessenger;
303 }
304
305 #endif // _Message_Messenger_HeaderFile