]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/log.h
Improve wxDatePickerCtrlGeneric best size calculation.
[wxWidgets.git] / interface / wx / log.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: log.h
54e280d8 3// Purpose: interface of wxLog* classes
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
23324ae1
FM
7/////////////////////////////////////////////////////////////////////////////
8
4a6665c6
FM
9
10/**
11 Different standard log levels (you may also define your own) used with
75e488d5 12 by standard wxLog functions wxLogGeneric(), wxLogError(), wxLogWarning(), etc...
4a6665c6
FM
13*/
14enum wxLogLevelValues
15{
16 wxLOG_FatalError, //!< program can't continue, abort immediately
17 wxLOG_Error, //!< a serious error, user must be informed about it
18 wxLOG_Warning, //!< user is normally informed about it but may be ignored
19 wxLOG_Message, //!< normal message (i.e. normal output of a non GUI app)
20 wxLOG_Status, //!< informational: might go to the status line of GUI app
21 wxLOG_Info, //!< informational message (a.k.a. 'Verbose')
22 wxLOG_Debug, //!< never shown to the user, disabled in release mode
23 wxLOG_Trace, //!< trace messages are also only enabled in debug mode
24 wxLOG_Progress, //!< used for progress indicator (not yet)
25 wxLOG_User = 100, //!< user defined levels start here
26 wxLOG_Max = 10000
27};
28
4a6665c6
FM
29/**
30 The type used to specify a log level.
31
32 Default values of ::wxLogLevel used by wxWidgets are contained in the
33 ::wxLogLevelValues enumeration.
34*/
35typedef unsigned long wxLogLevel;
36
bc73d5ae
VZ
37/**
38 Information about a log record (unit of the log output).
39 */
af588446 40class wxLogRecordInfo
bc73d5ae 41{
af588446
VZ
42public:
43 /// The name of the file where this log message was generated.
44 const char *filename;
45
46 /// The line number at which this log message was generated.
47 int line;
48
49 /**
50 The name of the function where the log record was generated.
51
52 This field may be @NULL if the compiler doesn't support @c __FUNCTION__
53 (but most modern compilers do).
54 */
55 const char *func;
56
bc73d5ae
VZ
57 /// Time when the log message was generated.
58 time_t timestamp;
59
60 /**
61 Id of the thread in which the message was generated.
62
63 This field is only available if wxWidgets was built with threads
64 support (<code>wxUSE_THREADS == 1</code>).
65
66 @see wxThread::GetCurrentId()
67 */
68 wxThreadIdType threadId;
69};
4a6665c6 70
23324ae1
FM
71/**
72 @class wxLogWindow
7c913512 73
23324ae1
FM
74 This class represents a background log window: to be precise, it collects all
75 log messages in the log frame which it manages but also passes them on to the
3e6f95dc 76 log target which was active at the moment of its creation. This allows you, for
23324ae1
FM
77 example, to show all the log messages in a frame but still continue to process
78 them normally by showing the standard log dialog.
7c913512 79
23324ae1
FM
80 @library{wxbase}
81 @category{logging}
7c913512 82
e54c96f1 83 @see wxLogTextCtrl
23324ae1
FM
84*/
85class wxLogWindow : public wxLogInterposer
86{
87public:
88 /**
89 Creates the log frame window and starts collecting the messages in it.
3c4f71cc 90
f21dd16b 91 @param pParent
4cc4bfaf 92 The parent window for the log frame, may be @NULL
f21dd16b 93 @param szTitle
4cc4bfaf 94 The title for the log frame
7c913512 95 @param show
4cc4bfaf
FM
96 @true to show the frame initially (default), otherwise
97 Show() must be called later.
7c913512 98 @param passToOld
54e280d8
FM
99 @true to process the log messages normally in addition to logging them
100 in the log frame (default), @false to only log them in the log frame.
101 Note that if no targets were set using wxLog::SetActiveTarget() then
102 wxLogWindow simply becomes the active one and messages won't be passed
103 to other targets.
23324ae1 104 */
fadc2df6 105 wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true,
4cc4bfaf 106 bool passToOld = true);
23324ae1
FM
107
108 /**
109 Returns the associated log frame window. This may be used to position or resize
110 it but use Show() to show or hide it.
111 */
328f5751 112 wxFrame* GetFrame() const;
23324ae1
FM
113
114 /**
115 Called if the user closes the window interactively, will not be
116 called if it is destroyed for another reason (such as when program
117 exits).
6a93e794 118
23324ae1
FM
119 Return @true from here to allow the frame to close, @false to
120 prevent this from happening.
3c4f71cc 121
4cc4bfaf 122 @see OnFrameDelete()
23324ae1 123 */
43c48e1e 124 virtual bool OnFrameClose(wxFrame* frame);
23324ae1
FM
125
126 /**
127 Called immediately after the log frame creation allowing for
128 any extra initializations.
129 */
43c48e1e 130 virtual void OnFrameCreate(wxFrame* frame);
23324ae1
FM
131
132 /**
133 Called right before the log frame is going to be deleted: will
134 always be called unlike OnFrameClose().
135 */
43c48e1e 136 virtual void OnFrameDelete(wxFrame* frame);
23324ae1
FM
137
138 /**
139 Shows or hides the frame.
140 */
4cc4bfaf 141 void Show(bool show = true);
23324ae1
FM
142};
143
144
e54c96f1 145
23324ae1
FM
146/**
147 @class wxLogInterposerTemp
7c913512 148
6a93e794
FM
149 A special version of wxLogChain which uses itself as the new log target.
150 It forwards log messages to the previously installed one in addition to
151 processing them itself. Unlike wxLogInterposer, it doesn't delete the old
152 target which means it can be used to temporarily redirect log output.
7c913512 153
23324ae1 154 As per wxLogInterposer, this class must be derived from to implement
6a93e794 155 wxLog::DoLog and/or wxLog::DoLogString methods.
7c913512 156
23324ae1
FM
157 @library{wxbase}
158 @category{logging}
159*/
160class wxLogInterposerTemp : public wxLogChain
161{
162public:
163 /**
164 The default constructor installs this object as the current active log target.
165 */
6a93e794 166 wxLogInterposerTemp();
23324ae1
FM
167};
168
169
e54c96f1 170
23324ae1
FM
171/**
172 @class wxLogChain
7c913512 173
3e6f95dc 174 This simple class allows you to chain log sinks, that is to install a new sink but
23324ae1
FM
175 keep passing log messages to the old one instead of replacing it completely as
176 wxLog::SetActiveTarget does.
7c913512 177
23324ae1
FM
178 It is especially useful when you want to divert the logs somewhere (for
179 example to a file or a log window) but also keep showing the error messages
180 using the standard dialogs as wxLogGui does by default.
7c913512 181
23324ae1 182 Example of usage:
7c913512 183
23324ae1
FM
184 @code
185 wxLogChain *logChain = new wxLogChain(new wxLogStderr);
7c913512 186
23324ae1
FM
187 // all the log messages are sent to stderr and also processed as usually
188 ...
7c913512 189
23324ae1
FM
190 // don't delete logChain directly as this would leave a dangling
191 // pointer as active log target, use SetActiveTarget() instead
6bfc18d0 192 delete wxLog::SetActiveTarget(...something else or NULL...);
23324ae1 193 @endcode
7c913512 194
23324ae1
FM
195 @library{wxbase}
196 @category{logging}
197*/
198class wxLogChain : public wxLog
199{
200public:
201 /**
202 Sets the specified @c logger (which may be @NULL) as the default log
203 target but the log messages are also passed to the previous log target if any.
204 */
4cc4bfaf 205 wxLogChain(wxLog* logger);
23324ae1
FM
206
207 /**
208 Destroys the previous log target.
209 */
adaaa686 210 virtual ~wxLogChain();
23324ae1
FM
211
212 /**
213 Detaches the old log target so it won't be destroyed when the wxLogChain object
214 is destroyed.
215 */
216 void DetachOldLog();
217
218 /**
219 Returns the pointer to the previously active log target (which may be @NULL).
220 */
328f5751 221 wxLog* GetOldLog() const;
23324ae1
FM
222
223 /**
224 Returns @true if the messages are passed to the previously active log
6a93e794 225 target (default) or @false if PassMessages() had been called.
23324ae1 226 */
328f5751 227 bool IsPassingMessages() const;
23324ae1
FM
228
229 /**
230 By default, the log messages are passed to the previously active log target.
231 Calling this function with @false parameter disables this behaviour
232 (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and
4cc4bfaf 233 it can be reenabled by calling it again with @a passMessages set to @true.
23324ae1
FM
234 */
235 void PassMessages(bool passMessages);
236
237 /**
6a93e794
FM
238 Sets another log target to use (may be @NULL).
239
240 The log target specified in the wxLogChain(wxLog*) constructor or in a
241 previous call to this function is deleted.
23324ae1
FM
242 This doesn't change the old log target value (the one the messages are
243 forwarded to) which still remains the same as was active when wxLogChain
244 object was created.
245 */
4cc4bfaf 246 void SetLog(wxLog* logger);
23324ae1
FM
247};
248
249
e54c96f1 250
23324ae1
FM
251/**
252 @class wxLogGui
7c913512 253
5d815500
VZ
254 This is the default log target for the GUI wxWidgets applications.
255
256 Please see @ref overview_log_customize for explanation of how to change the
257 default log target.
258
259 An object of this class is used by default to show the log messages created
260 by using wxLogMessage(), wxLogError() and other logging functions. It
261 doesn't display the messages logged by them immediately however but
262 accumulates all messages logged during an event handler execution and then
263 shows them all at once when its Flush() method is called during the idle
264 time processing. This has the important advantage of showing only a single
265 dialog to the user even if several messages were logged because of a single
266 error as it often happens (e.g. a low level function could log a message
267 because it failed to open a file resulting in its caller logging another
268 message due to the failure of higher level operation requiring the use of
269 this file). If you need to force the display of all previously logged
270 messages immediately you can use wxLog::FlushActive() to force the dialog
271 display.
272
273 Also notice that if an error message is logged when several informative
274 messages had been already logged before, the informative messages are
275 discarded on the assumption that they are not useful -- and may be
276 confusing and hence harmful -- any more after the error. The warning
277 and error messages are never discarded however and any informational
278 messages logged after the first error one are also kept (as they may
279 contain information about the error recovery). You may override DoLog()
280 method to change this behaviour.
281
282 At any rate, it is possible that that several messages were accumulated
283 before this class Flush() method is called. If this is the case, Flush()
284 uses a custom dialog which shows the last message directly and allows the
285 user to view the previously logged ones by expanding the "Details"
286 wxCollapsiblePane inside it. This custom dialog also provides the buttons
287 for copying the log messages to the clipboard and saving them to a file.
288
289 However if only a single message is present when Flush() is called, just a
290 wxMessageBox() is used to show it. This has the advantage of being closer
291 to the native behaviour but it doesn't give the user any possibility to
292 copy or save the message (except for the recent Windows versions where @c
293 Ctrl-C may be pressed in the message box to copy its contents to the
21371c1d
VZ
294 clipboard) so you may want to override DoShowSingleLogMessage() to
295 customize wxLogGui -- the dialogs sample shows how to do this.
7c913512 296
5d815500 297 @library{wxcore}
23324ae1
FM
298 @category{logging}
299*/
300class wxLogGui : public wxLog
301{
302public:
303 /**
304 Default constructor.
305 */
306 wxLogGui();
5d815500
VZ
307
308 /**
309 Presents the accumulated log messages, if any, to the user.
310
311 This method is called during the idle time and should show any messages
312 accumulated in wxLogGui#m_aMessages field to the user.
313 */
314 virtual void Flush();
315
316protected:
317 /**
318 Returns the appropriate title for the dialog.
319
320 The title is constructed from wxApp::GetAppDisplayName() and the
321 severity string (e.g. "error" or "warning") appropriate for the current
322 wxLogGui#m_bErrors and wxLogGui#m_bWarnings values.
323 */
324 wxString GetTitle() const;
325
326 /**
327 Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on
328 the current maximal severity.
329
330 This value is suitable to be used in the style parameter of
331 wxMessageBox() function.
332 */
333 int GetSeverityIcon() const;
334
335 /**
336 Forgets all the currently stored messages.
337
338 If you override Flush() (and don't call the base class version), you
339 must call this method to avoid messages being logged over and over
340 again.
341 */
342 void Clear();
343
344
5d815500
VZ
345 /**
346 All currently accumulated messages.
347
348 This array may be empty if no messages were logged.
349
350 @see m_aSeverity, m_aTimes
351 */
352 wxArrayString m_aMessages;
353
354 /**
355 The severities of each logged message.
356
357 This array is synchronized with wxLogGui#m_aMessages, i.e. the n-th
358 element of this array corresponds to the severity of the n-th message.
359 The possible severity values are @c wxLOG_XXX constants, e.g.
360 wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.
361 */
362 wxArrayInt m_aSeverity;
363
364 /**
365 The time stamps of each logged message.
366
367 The elements of this array are time_t values corresponding to the time
368 when the message was logged.
369 */
370 wxArrayLong m_aTimes;
371
372 /**
373 True if there any error messages.
374 */
375 bool m_bErrors;
376
377 /**
378 True if there any warning messages.
379
380 If both wxLogGui#m_bErrors and this member are false, there are only
381 informational messages to be shown.
382 */
383 bool m_bWarnings;
384
385 /**
386 True if there any messages to be shown to the user.
387
388 This variable is used instead of simply checking whether
389 wxLogGui#m_aMessages array is empty to allow blocking further calls to
390 Flush() while a log dialog is already being shown, even if the messages
391 array hasn't been emptied yet.
392 */
393 bool m_bHasMessages;
21371c1d
VZ
394
395private:
396 /**
397 Method called by Flush() to show a single log message.
398
399 This function can be overridden to show the message in a different way.
400 By default a simple wxMessageBox() call is used.
401
402 @param message
403 The message to show (it can contain multiple lines).
404 @param title
405 The suggested title for the dialog showing the message, see
406 GetTitle().
407 @param style
408 One of @c wxICON_XXX constants, see GetSeverityIcon().
409 */
410 virtual void DoShowSingleLogMessage(const wxString& message,
411 const wxString& title,
412 int style);
413
414 /**
415 Method called by Flush() to show multiple log messages.
416
417 This function can be overridden to show the messages in a different way.
418 By default a special log dialog showing the most recent message and
419 allowing the user to expand it to view the previously logged ones is
420 used.
421
422 @param messages
423 Array of messages to show; it contains more than one element.
424 @param severities
425 Array of message severities containing @c wxLOG_XXX values.
426 @param times
427 Array of time_t values indicating when each message was logged.
428 @param title
429 The suggested title for the dialog showing the message, see
430 GetTitle().
431 @param style
432 One of @c wxICON_XXX constants, see GetSeverityIcon().
433 */
434 virtual void DoShowMultipleLogMessages(const wxArrayString& messages,
435 const wxArrayInt& severities,
436 const wxArrayLong& times,
437 const wxString& title,
438 int style);
23324ae1
FM
439};
440
441
e54c96f1 442
23324ae1
FM
443/**
444 @class wxLogStream
7c913512 445
23324ae1 446 This class can be used to redirect the log messages to a C++ stream.
7c913512 447
23324ae1
FM
448 Please note that this class is only available if wxWidgets was compiled with
449 the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on).
7c913512 450
23324ae1
FM
451 @library{wxbase}
452 @category{logging}
7c913512 453
e54c96f1 454 @see wxLogStderr, wxStreamToTextRedirector
23324ae1
FM
455*/
456class wxLogStream : public wxLog
457{
458public:
459 /**
460 Constructs a log target which sends all the log messages to the given
461 output stream. If it is @NULL, the messages are sent to @c cerr.
462 */
0a98423e 463 wxLogStream(std::ostream *ostr = NULL);
23324ae1
FM
464};
465
466
e54c96f1 467
23324ae1
FM
468/**
469 @class wxLogStderr
7c913512 470
23324ae1 471 This class can be used to redirect the log messages to a C file stream (not to
a44f3b5a
FM
472 be confused with C++ streams).
473
474 It is the default log target for the non-GUI wxWidgets applications which
475 send all the output to @c stderr.
7c913512 476
23324ae1
FM
477 @library{wxbase}
478 @category{logging}
7c913512 479
e54c96f1 480 @see wxLogStream
23324ae1
FM
481*/
482class wxLogStderr : public wxLog
483{
484public:
485 /**
486 Constructs a log target which sends all the log messages to the given
487 @c FILE. If it is @NULL, the messages are sent to @c stderr.
488 */
8067ee11 489 wxLogStderr(FILE* fp = NULL);
23324ae1
FM
490};
491
492
e54c96f1 493
23324ae1
FM
494/**
495 @class wxLogBuffer
7c913512 496
23324ae1
FM
497 wxLogBuffer is a very simple implementation of log sink which simply collects
498 all the logged messages in a string (except the debug messages which are output
499 in the usual way immediately as we're presumably not interested in collecting
500 them for later). The messages from different log function calls are separated
501 by the new lines.
7c913512 502
23324ae1 503 All the messages collected so far can be shown to the user (and the current
6a93e794 504 buffer cleared) by calling the overloaded wxLogBuffer::Flush method.
7c913512 505
23324ae1 506 @library{wxbase}
3e6f95dc 507 @category{logging}
23324ae1
FM
508*/
509class wxLogBuffer : public wxLog
510{
511public:
435c1bc4
FM
512 /**
513 The default ctor does nothing.
514 */
515 wxLogBuffer();
516
23324ae1
FM
517 /**
518 Shows all the messages collected so far to the user (using a message box in the
519 GUI applications or by printing them out to the console in text mode) and
520 clears the internal buffer.
521 */
522 virtual void Flush();
523
524 /**
525 Returns the current buffer contains. Messages from different log function calls
526 are separated with the new lines in the buffer.
6a93e794
FM
527 The buffer can be cleared by Flush() which will also show the current
528 contents to the user.
23324ae1 529 */
43c48e1e 530 const wxString& GetBuffer() const;
23324ae1
FM
531};
532
533
e54c96f1 534
23324ae1
FM
535/**
536 @class wxLogInterposer
7c913512 537
6a93e794
FM
538 A special version of wxLogChain which uses itself as the new log target.
539 It forwards log messages to the previously installed one in addition to
23324ae1 540 processing them itself.
7c913512 541
6a93e794
FM
542 Unlike wxLogChain which is usually used directly as is, this class must be
543 derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods.
7c913512 544
6a93e794
FM
545 wxLogInterposer destroys the previous log target in its destructor.
546 If you don't want this to happen, use wxLogInterposerTemp instead.
7c913512 547
23324ae1
FM
548 @library{wxbase}
549 @category{logging}
550*/
551class wxLogInterposer : public wxLogChain
552{
553public:
554 /**
555 The default constructor installs this object as the current active log target.
556 */
6a93e794 557 wxLogInterposer();
23324ae1
FM
558};
559
560
e54c96f1 561
23324ae1
FM
562/**
563 @class wxLogTextCtrl
7c913512 564
23324ae1
FM
565 Using these target all the log messages can be redirected to a text control.
566 The text control must have been created with @c wxTE_MULTILINE style by the
567 caller previously.
7c913512 568
23324ae1
FM
569 @library{wxbase}
570 @category{logging}
7c913512 571
e54c96f1 572 @see wxTextCtrl, wxStreamToTextRedirector
23324ae1
FM
573*/
574class wxLogTextCtrl : public wxLog
575{
576public:
577 /**
578 Constructs a log target which sends all the log messages to the given text
4cc4bfaf 579 control. The @a textctrl parameter cannot be @NULL.
23324ae1 580 */
8067ee11 581 wxLogTextCtrl(wxTextCtrl* pTextCtrl);
23324ae1
FM
582};
583
584
e54c96f1 585
4ffdb640
VZ
586
587/**
588 @class wxLogFormatter
589
590 wxLogFormatter class is used to format the log messages. It implements the
591 default formatting and can be derived from to create custom formatters.
592
593 The default implementation formats the message into a string containing
594 the time stamp, level-dependent prefix and the message itself.
595
596 To change it, you can derive from it and override its Format() method. For
597 example, to include the thread id in the log messages you can use
598 @code
599 class LogFormatterWithThread : public wxLogFormatter
600 {
601 virtual wxString Format(wxLogLevel level,
602 const wxString& msg,
603 const wxLogRecordInfo& info) const
604 {
605 return wxString::Format("[%d] %s(%d) : %s",
606 info.threadId, info.filename, info.line, msg);
607 }
608 };
609 @endcode
610 And then associate it with wxLog instance using its SetFormatter(). Then,
611 if you call:
612
613 @code
614 wxLogMessage(_("*** Application started ***"));
615 @endcode
616
617 the log output could be something like:
618
619 @verbatim
620 [7872] d:\testApp\src\testApp.cpp(85) : *** Application started ***
621 @endverbatim
622
623 @library{wxbase}
624 @category{logging}
625
626 @see @ref overview_log
627
628 @since 2.9.4
629*/
630class wxLogFormatter
631{
632public:
633 /**
634 The default ctor does nothing.
635 */
636 wxLogFormatter();
637
638
639 /**
640 This function creates the full log message string.
641
642 Override it to customize the output string format.
643
644 @param level
645 The level of this log record, e.g. ::wxLOG_Error.
646 @param msg
647 The log message itself.
648 @param info
649 All the other information (such as time, component, location...)
650 associated with this log record.
651
652 @return
653 The formated message.
654
655 @note
656 Time stamping is disabled for Visual C++ users in debug builds by
657 default because otherwise it would be impossible to directly go to the line
658 from which the log message was generated by simply clicking in the debugger
659 window on the corresponding error message. If you wish to enable it, override
660 FormatTime().
661 */
662 virtual wxString Format(wxLogLevel level,
663 const wxString& msg,
664 const wxLogRecordInfo& info) const;
665
666protected:
667 /**
668 This function formats the time stamp part of the log message.
669
670 Override this function if you need to customize just the time stamp.
671
672 @param time
673 Time to format.
674
675 @return
676 The formated time string, may be empty.
677 */
678 virtual wxString FormatTime(time_t time) const;
679};
680
681
23324ae1
FM
682/**
683 @class wxLog
7c913512 684
54e280d8 685 wxLog class defines the interface for the <em>log targets</em> used by wxWidgets
3e6f95dc 686 logging functions as explained in the @ref overview_log.
54e280d8 687
23324ae1
FM
688 The only situations when you need to directly use this class is when you want
689 to derive your own log target because the existing ones don't satisfy your
54e280d8 690 needs.
7c913512 691
54e280d8
FM
692 Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions"
693 and you may not even know about its existence.
7c913512 694
a44f3b5a
FM
695 @note For console-mode applications, the default target is wxLogStderr, so
696 that all @e wxLogXXX() functions print on @c stderr when @c wxUSE_GUI = 0.
697
4ffdb640 698 @library{wxbase}
5bc128d6 699 @category{logging}
3c4f71cc 700
54e280d8 701 @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions"
5bc128d6
RR
702*/
703class wxLog
704{
705public:
54e280d8
FM
706 /**
707 @name Trace mask functions
708 */
709 //@{
710
5bc128d6 711 /**
6a93e794 712 Add the @a mask to the list of allowed masks for wxLogTrace().
3c4f71cc 713
5bc128d6
RR
714 @see RemoveTraceMask(), GetTraceMasks()
715 */
716 static void AddTraceMask(const wxString& mask);
3c4f71cc 717
5bc128d6 718 /**
6a93e794 719 Removes all trace masks previously set with AddTraceMask().
3c4f71cc 720
5bc128d6
RR
721 @see RemoveTraceMask()
722 */
723 static void ClearTraceMasks();
3c4f71cc 724
23324ae1 725 /**
54e280d8 726 Returns the currently allowed list of string trace masks.
6a93e794 727
54e280d8 728 @see AddTraceMask().
23324ae1 729 */
54e280d8 730 static const wxArrayString& GetTraceMasks();
23324ae1 731
ba3af101 732 /**
54e280d8 733 Returns @true if the @a mask is one of allowed masks for wxLogTrace().
ba3af101 734
54e280d8
FM
735 See also: AddTraceMask(), RemoveTraceMask()
736 */
737 static bool IsAllowedTraceMask(const wxString& mask);
ba3af101 738
54e280d8
FM
739 /**
740 Remove the @a mask from the list of allowed masks for
741 wxLogTrace().
ba3af101 742
54e280d8
FM
743 @see AddTraceMask()
744 */
745 static void RemoveTraceMask(const wxString& mask);
746
747 //@}
ba3af101 748
232addd1 749
232addd1 750
54e280d8
FM
751 /**
752 @name Log target functions
23324ae1 753 */
54e280d8
FM
754 //@{
755
23324ae1 756 /**
54e280d8
FM
757 Instructs wxLog to not create new log targets on the fly if there is none
758 currently (see GetActiveTarget()).
759
760 (Almost) for internal use only: it is supposed to be called by the
761 application shutdown code (where you don't want the log target to be
762 automatically created anymore).
3c4f71cc 763
54e280d8 764 Note that this function also calls ClearTraceMasks().
23324ae1 765 */
54e280d8 766 static void DontCreateOnDemand();
23324ae1
FM
767
768 /**
769 Returns the pointer to the active log target (may be @NULL).
acad886c
VZ
770
771 Notice that if SetActiveTarget() hadn't been previously explicitly
772 called, this function will by default try to create a log target by
773 calling wxAppTraits::CreateLogTarget() which may be overridden in a
774 user-defined traits class to change the default behaviour. You may also
775 call DontCreateOnDemand() to disable this behaviour.
776
777 When this function is called from threads other than main one,
778 auto-creation doesn't happen. But if the thread has a thread-specific
779 log target previously set by SetThreadActiveTarget(), it is returned
780 instead of the global one. Otherwise, the global log target is
781 returned.
23324ae1 782 */
4cc4bfaf 783 static wxLog* GetActiveTarget();
23324ae1
FM
784
785 /**
54e280d8 786 Sets the specified log target as the active one.
ba3af101 787
54e280d8
FM
788 Returns the pointer to the previous active log target (may be @NULL).
789 To suppress logging use a new instance of wxLogNull not @NULL. If the
790 active log target is set to @NULL a new default log target will be
791 created when logging occurs.
ba3af101 792
54e280d8 793 @see SetThreadActiveTarget()
23324ae1 794 */
54e280d8 795 static wxLog* SetActiveTarget(wxLog* logtarget);
23324ae1
FM
796
797 /**
54e280d8 798 Sets a thread-specific log target.
23324ae1 799
54e280d8
FM
800 The log target passed to this function will be used for all messages
801 logged by the current thread using the usual wxLog functions. This
802 shouldn't be called from the main thread which never uses a thread-
803 specific log target but can be used for the other threads to handle
804 thread logging completely separately; instead of buffering thread log
805 messages in the main thread logger.
23324ae1 806
54e280d8
FM
807 Notice that unlike for SetActiveTarget(), wxWidgets does not destroy
808 the thread-specific log targets when the thread terminates so doing
809 this is your responsibility.
810
811 This method is only available if @c wxUSE_THREADS is 1, i.e. wxWidgets
812 was compiled with threads support.
813
814 @param logger
815 The new thread-specific log target, possibly @NULL.
816 @return
817 The previous thread-specific log target, initially @NULL.
23324ae1 818
54e280d8
FM
819 @since 2.9.1
820 */
821 static wxLog *SetThreadActiveTarget(wxLog *logger);
822
23324ae1 823 /**
54e280d8 824 Flushes the current log target if any, does nothing if there is none.
3c4f71cc 825
54e280d8
FM
826 When this method is called from the main thread context, it also
827 flushes any previously buffered messages logged by the other threads.
828 When it is called from the other threads it simply calls Flush() on the
829 currently active log target, so it mostly makes sense to do this if a
830 thread has its own logger set with SetThreadActiveTarget().
23324ae1 831 */
54e280d8
FM
832 static void FlushActive();
833
23324ae1 834 /**
54e280d8
FM
835 Resumes logging previously suspended by a call to Suspend().
836 All messages logged in the meanwhile will be flushed soon.
23324ae1 837 */
54e280d8 838 static void Resume();
23324ae1 839
23324ae1 840 /**
54e280d8 841 Suspends the logging until Resume() is called.
8067ee11 842
54e280d8
FM
843 Note that the latter must be called the same number of times as the former
844 to undo it, i.e. if you call Suspend() twice you must call Resume() twice as well.
845
d13b34d3 846 Note that suspending the logging means that the log sink won't be flushed
54e280d8
FM
847 periodically, it doesn't have any effect if the current log target does the
848 logging immediately without waiting for Flush() to be called (the standard
849 GUI log target only shows the log dialog when it is flushed, so Suspend()
850 works as expected with it).
851
852 @see Resume(), wxLogNull
23324ae1 853 */
54e280d8
FM
854 static void Suspend();
855
856 //@}
857
858
23324ae1 859
ba3af101 860 /**
54e280d8
FM
861 @name Log level functions
862 */
863 //@{
864
865 /**
866 Returns the current log level limit.
ba3af101 867
54e280d8
FM
868 All messages at levels strictly greater than the value returned by this
869 function are not logged at all.
ba3af101 870
54e280d8
FM
871 @see SetLogLevel(), IsLevelEnabled()
872 */
873 static wxLogLevel GetLogLevel();
874
ba3af101 875 /**
53ff8df7 876 Returns true if logging at this level is enabled for the current thread.
ba3af101
VZ
877
878 This function only returns @true if logging is globally enabled and if
c602c59b
VZ
879 @a level is less than or equal to the maximal log level enabled for the
880 given @a component.
ba3af101 881
c602c59b
VZ
882 @see IsEnabled(), SetLogLevel(), GetLogLevel(), SetComponentLevel()
883
884 @since 2.9.1
ba3af101 885 */
c602c59b 886 static bool IsLevelEnabled(wxLogLevel level, wxString component);
ba3af101 887
c602c59b
VZ
888 /**
889 Sets the log level for the given component.
890
891 For example, to disable all but error messages from wxWidgets network
892 classes you may use
893 @code
894 wxLog::SetComponentLevel("wx/net", wxLOG_Error);
895 @endcode
896
897 SetLogLevel() may be used to set the global log level.
898
899 @param component
900 Non-empty component name, possibly using slashes (@c /) to separate
901 it into several parts.
902 @param level
903 Maximal level of log messages from this component which will be
904 handled instead of being simply discarded.
905
906 @since 2.9.1
907 */
908 static void SetComponentLevel(const wxString& component, wxLogLevel level);
909
23324ae1 910 /**
4a6665c6
FM
911 Specifies that log messages with level greater (numerically) than
912 @a logLevel should be ignored and not sent to the active log target.
c602c59b
VZ
913
914 @see SetComponentLevel()
23324ae1
FM
915 */
916 static void SetLogLevel(wxLogLevel logLevel);
54e280d8
FM
917
918 //@}
919
920
23324ae1
FM
921
922 /**
54e280d8 923 @name Enable/disable features functions
23324ae1 924 */
54e280d8
FM
925 //@{
926
acad886c 927 /**
54e280d8 928 Globally enable or disable logging.
acad886c 929
54e280d8
FM
930 Calling this function with @false argument disables all log messages
931 for the current thread.
acad886c 932
54e280d8 933 @see wxLogNull, IsEnabled()
acad886c 934
acad886c 935 @return
54e280d8
FM
936 The old state, i.e. @true if logging was previously enabled and
937 @false if it was disabled.
938 */
939 static bool EnableLogging(bool enable = true);
acad886c 940
54e280d8
FM
941 /**
942 Returns true if logging is enabled at all now.
943
944 @see IsLevelEnabled(), EnableLogging()
acad886c 945 */
54e280d8
FM
946 static bool IsEnabled();
947
948 /**
949 Returns whether the repetition counting mode is enabled.
950 */
951 static bool GetRepetitionCounting();
952
953 /**
954 Enables logging mode in which a log message is logged once, and in case exactly
955 the same message successively repeats one or more times, only the number of
956 repetitions is logged.
957 */
958 static void SetRepetitionCounting(bool repetCounting = true);
959
960 /**
961 Returns the current timestamp format string.
4ffdb640
VZ
962
963 Notice that the current time stamp is only used by the default log
964 formatter and custom formatters may ignore this format.
54e280d8
FM
965 */
966 static const wxString& GetTimestamp();
acad886c 967
23324ae1
FM
968 /**
969 Sets the timestamp format prepended by the default log targets to all
970 messages. The string may contain any normal characters as well as %
d13b34d3 971 prefixed format specifiers, see @e strftime() manual for details.
23324ae1 972 Passing an empty string to this function disables message time stamping.
4ffdb640
VZ
973
974 Notice that the current time stamp is only used by the default log
975 formatter and custom formatters may ignore this format. You can also
976 define a custom wxLogFormatter to customize the time stamp handling
977 beyond changing its format.
23324ae1
FM
978 */
979 static void SetTimestamp(const wxString& format);
980
bce9df55
FM
981 /**
982 Disables time stamping of the log messages.
983
4ffdb640
VZ
984 Notice that the current time stamp is only used by the default log
985 formatter and custom formatters may ignore calls to this function.
986
bce9df55
FM
987 @since 2.9.0
988 */
989 static void DisableTimestamp();
54e280d8 990
23324ae1 991 /**
54e280d8 992 Returns whether the verbose mode is currently active.
23324ae1 993 */
54e280d8 994 static bool GetVerbose();
23324ae1
FM
995
996 /**
997 Activates or deactivates verbose mode in which the verbose messages are
998 logged as the normal ones instead of being silently dropped.
54e280d8
FM
999
1000 The verbose messages are the trace messages which are not disabled in the
1001 release mode and are generated by wxLogVerbose().
1002
1003 @see @ref overview_log
23324ae1 1004 */
4cc4bfaf 1005 static void SetVerbose(bool verbose = true);
54e280d8
FM
1006
1007 //@}
1008
4ffdb640
VZ
1009
1010 /**
1011 Sets the specified formatter as the active one.
1012
1013 @param formatter
1014 The new formatter. If @NULL, reset to the default formatter.
1015
1016 Returns the pointer to the previous formatter. You must delete it
1017 if you don't plan to attach it again to a wxLog object later.
1018
1019 @since 2.9.4
1020 */
1021 wxLogFormatter *SetFormatter(wxLogFormatter* formatter);
54e280d8 1022
23324ae1
FM
1023
1024 /**
54e280d8
FM
1025 Some of wxLog implementations, most notably the standard wxLogGui class,
1026 buffer the messages (for example, to avoid showing the user a zillion of modal
1027 message boxes one after another -- which would be really annoying).
1028 This function shows them all and clears the buffer contents.
1029 If the buffer is already empty, nothing happens.
3c4f71cc 1030
54e280d8
FM
1031 If you override this method in a derived class, call the base class
1032 version first, before doing anything else.
23324ae1 1033 */
54e280d8
FM
1034 virtual void Flush();
1035
efce878a 1036 /**
bc73d5ae 1037 Log the given record.
efce878a
VZ
1038
1039 This function should only be called from the DoLog() implementations in
bc73d5ae
VZ
1040 the derived classes if they need to call DoLogRecord() on another log
1041 object (they can, of course, just use wxLog::DoLogRecord() call syntax
1042 to call it on the object itself). It should not be used for logging new
1043 messages which can be only sent to the currently active logger using
1044 OnLog() which also checks if the logging (for this level) is enabled
1045 while this method just directly calls DoLog().
efce878a
VZ
1046
1047 Example of use of this class from wxLogChain:
1048 @code
bc73d5ae
VZ
1049 void wxLogChain::DoLogRecord(wxLogLevel level,
1050 const wxString& msg,
1051 const wxLogRecordInfo& info)
efce878a
VZ
1052 {
1053 // let the previous logger show it
1054 if ( m_logOld && IsPassingMessages() )
bc73d5ae 1055 m_logOld->LogRecord(level, msg, info);
efce878a
VZ
1056
1057 // and also send it to the new one
1058 if ( m_logNew && m_logNew != this )
bc73d5ae 1059 m_logNew->LogRecord(level, msg, info);
efce878a
VZ
1060 }
1061 @endcode
1062
bc73d5ae 1063 @since 2.9.1
efce878a 1064 */
86381d42 1065 void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info);
efce878a 1066
5e6e278d 1067protected:
bc73d5ae
VZ
1068 /**
1069 @name Logging callbacks.
1070
1071 The functions which should be overridden by custom log targets.
1072
1073 When defining a new log target, you have a choice between overriding
1074 DoLogRecord(), which provides maximal flexibility, DoLogTextAtLevel()
1075 which can be used if you don't intend to change the default log
1076 messages formatting but want to handle log messages of different levels
1077 differently or, in the simplest case, DoLogText().
1078 */
1079 //@{
5e6e278d
FM
1080
1081 /**
85898d8b 1082 Called to log a new record.
bc73d5ae
VZ
1083
1084 Any log message created by wxLogXXX() functions is passed to this
1085 method of the active log target. The default implementation prepends
1086 the timestamp and, for some log levels (e.g. error and warning), the
1087 corresponding prefix to @a msg and passes it to DoLogTextAtLevel().
5e6e278d 1088
bc73d5ae
VZ
1089 You may override this method to implement custom formatting of the
1090 log messages or to implement custom filtering of log messages (e.g. you
1091 could discard all log messages coming from the given source file).
1092 */
1093 virtual void DoLogRecord(wxLogLevel level,
1094 const wxString& msg,
1095 const wxLogRecordInfo& info);
1096
1097 /**
1098 Called to log the specified string at given level.
1099
1100 The base class versions logs debug and trace messages on the system
1101 default debug output channel and passes all the other messages to
1102 DoLogText().
5e6e278d 1103 */
bc73d5ae 1104 virtual void DoLogTextAtLevel(wxLogLevel level, const wxString& msg);
5e6e278d
FM
1105
1106 /**
bc73d5ae 1107 Called to log the specified string.
5e6e278d 1108
bc73d5ae
VZ
1109 A simple implementation might just send the string to @c stdout or
1110 @c stderr or save it in a file (of course, the already existing
1111 wxLogStderr can be used for this).
1112
1113 The base class version of this function asserts so it must be
1114 overridden if you don't override DoLogRecord() or DoLogTextAtLevel().
5e6e278d 1115 */
bc73d5ae
VZ
1116 virtual void DoLogText(const wxString& msg);
1117
1118 //@}
23324ae1
FM
1119};
1120
1121
e54c96f1 1122
23324ae1
FM
1123/**
1124 @class wxLogNull
7c913512 1125
3e6f95dc 1126 This class allows you to temporarily suspend logging. All calls to the log
23324ae1 1127 functions during the life time of an object of this class are just ignored.
7c913512 1128
23324ae1
FM
1129 In particular, it can be used to suppress the log messages given by wxWidgets
1130 itself but it should be noted that it is rarely the best way to cope with this
1131 problem as @b all log messages are suppressed, even if they indicate a
1132 completely different error than the one the programmer wanted to suppress.
7c913512 1133
23324ae1 1134 For instance, the example of the overview:
7c913512 1135
23324ae1 1136 @code
6a93e794 1137 wxFile file;
7c913512 1138
23324ae1
FM
1139 // wxFile.Open() normally complains if file can't be opened, we don't want it
1140 {
1141 wxLogNull logNo;
1142 if ( !file.Open("bar") )
1143 ... process error ourselves ...
1144 } // ~wxLogNull called, old log sink restored
7c913512 1145
23324ae1
FM
1146 wxLogMessage("..."); // ok
1147 @endcode
7c913512 1148
23324ae1 1149 would be better written as:
7c913512 1150
23324ae1 1151 @code
6a93e794 1152 wxFile file;
7c913512 1153
23324ae1
FM
1154 // don't try to open file if it doesn't exist, we are prepared to deal with
1155 // this ourselves - but all other errors are not expected
1156 if ( wxFile::Exists("bar") )
1157 {
1158 // gives an error message if the file couldn't be opened
1159 file.Open("bar");
1160 }
1161 else
1162 {
1163 ...
1164 }
1165 @endcode
7c913512
FM
1166
1167
23324ae1
FM
1168 @library{wxbase}
1169 @category{logging}
1170*/
6a9994cf 1171class wxLogNull
23324ae1
FM
1172{
1173public:
1174 /**
1175 Suspends logging.
1176 */
1177 wxLogNull();
1178
1179 /**
1180 Resumes logging.
1181 */
6a93e794 1182 ~wxLogNull();
23324ae1
FM
1183};
1184
1185
e54c96f1 1186
23324ae1
FM
1187// ============================================================================
1188// Global functions/macros
1189// ============================================================================
1190
b21126db 1191/** @addtogroup group_funcmacro_log */
ef477678
BP
1192//@{
1193
23324ae1 1194/**
ef477678
BP
1195 This function shows a message to the user in a safe way and should be safe
1196 to call even before the application has been initialized or if it is
1197 currently in some other strange state (for example, about to crash). Under
1198 Windows this function shows a message box using a native dialog instead of
1199 wxMessageBox() (which might be unsafe to call), elsewhere it simply prints
1200 the message to the standard output using the title as prefix.
7c913512
FM
1201
1202 @param title
ef477678
BP
1203 The title of the message box shown to the user or the prefix of the
1204 message string.
7c913512 1205 @param text
ef477678 1206 The text to show to the user.
7c913512 1207
e54c96f1 1208 @see wxLogFatalError()
ef477678
BP
1209
1210 @header{wx/log.h}
23324ae1 1211*/
ef477678
BP
1212void wxSafeShowMessage(const wxString& title, const wxString& text);
1213
1214/**
1215 Returns the error code from the last system call. This function uses
1216 @c errno on Unix platforms and @c GetLastError under Win32.
23324ae1 1217
ef477678 1218 @see wxSysErrorMsg(), wxLogSysError()
96d7cc9b 1219
ef477678
BP
1220 @header{wx/log.h}
1221*/
1222unsigned long wxSysErrorCode();
96d7cc9b 1223
ef477678
BP
1224/**
1225 Returns the error message corresponding to the given system error code. If
1226 @a errCode is 0 (default), the last error code (as returned by
1227 wxSysErrorCode()) is used.
1228
1229 @see wxSysErrorCode(), wxLogSysError()
1230
1231 @header{wx/log.h}
1232*/
1233const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
1234
1235//@}
1236
75e488d5
FM
1237/** @addtogroup group_funcmacro_log */
1238//@{
1239/**
1240 Logs a message with the given wxLogLevel.
1241 E.g. using @c wxLOG_Message as first argument, this function behaves like wxLogMessage().
1242
1243 @header{wx/log.h}
1244*/
1245void wxLogGeneric(wxLogLevel level, const char* formatString, ... );
1246void wxVLogGeneric(wxLogLevel level, const char* formatString, va_list argPtr);
1247//@}
1248
b21126db 1249/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1250//@{
1251/**
ef477678
BP
1252 For all normal, informational messages. They also appear in a message box
1253 by default (but it can be changed).
1254
1255 @header{wx/log.h}
96d7cc9b
FM
1256*/
1257void wxLogMessage(const char* formatString, ... );
1258void wxVLogMessage(const char* formatString, va_list argPtr);
1259//@}
1260
b21126db 1261/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1262//@{
1263/**
ef477678
BP
1264 For verbose output. Normally, it is suppressed, but might be activated if
1265 the user wishes to know more details about the program progress (another,
1266 but possibly confusing name for the same function could be @c wxLogInfo).
1267
1268 @header{wx/log.h}
96d7cc9b
FM
1269*/
1270void wxLogVerbose(const char* formatString, ... );
1271void wxVLogVerbose(const char* formatString, va_list argPtr);
1272//@}
1273
b21126db 1274/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1275//@{
1276/**
ef477678
BP
1277 For warnings - they are also normally shown to the user, but don't
1278 interrupt the program work.
1279
1280 @header{wx/log.h}
96d7cc9b
FM
1281*/
1282void wxLogWarning(const char* formatString, ... );
1283void wxVLogWarning(const char* formatString, va_list argPtr);
1284//@}
1285
b21126db 1286/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1287//@{
1288/**
ef477678
BP
1289 Like wxLogError(), but also terminates the program with the exit code 3.
1290 Using @e abort() standard function also terminates the program with this
1291 exit code.
1292
1293 @header{wx/log.h}
96d7cc9b
FM
1294*/
1295void wxLogFatalError(const char* formatString, ... );
ef477678 1296void wxVLogFatalError(const char* formatString, va_list argPtr);
96d7cc9b
FM
1297//@}
1298
b21126db 1299/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1300//@{
1301/**
ef477678
BP
1302 The functions to use for error messages, i.e. the messages that must be
1303 shown to the user. The default processing is to pop up a message box to
1304 inform the user about it.
1305
1306 @header{wx/log.h}
96d7cc9b
FM
1307*/
1308void wxLogError(const char* formatString, ... );
1309void wxVLogError(const char* formatString, va_list argPtr);
1310//@}
1311
b21126db 1312/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1313//@{
1314/**
695d5232 1315 Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum).
7bfc1038
VZ
1316
1317 Notice that the use of trace masks is not recommended any more as setting
1318 the log components (please see @ref overview_log_enable) provides a way to
1319 do the same thing for log messages of any level, and not just the tracing
1320 ones.
1321
ef477678
BP
1322 Like wxLogDebug(), trace functions only do something in debug builds and
1323 expand to nothing in the release one. The reason for making it a separate
1324 function is that usually there are a lot of trace messages, so it might
1325 make sense to separate them from other debug messages.
1326
695d5232
FM
1327 Trace messages can be separated into different categories; these functions in facts
1328 only log the message if the given @a mask is currently enabled in wxLog.
1329 This lets you selectively trace only some operations and not others by enabling the
1330 desired trace masks with wxLog::AddTraceMask() or by setting the
ef477678
BP
1331 @ref overview_envvars "@c WXTRACE environment variable".
1332
1333 The predefined string trace masks used by wxWidgets are:
1334
1335 @beginDefList
1336 @itemdef{ wxTRACE_MemAlloc, Trace memory allocation (new/delete) }
1337 @itemdef{ wxTRACE_Messages, Trace window messages/X callbacks }
1338 @itemdef{ wxTRACE_ResAlloc, Trace GDI resource allocation }
1339 @itemdef{ wxTRACE_RefCount, Trace various ref counting operations }
1340 @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) }
1341 @endDefList
1342
ef477678
BP
1343 @header{wx/log.h}
1344*/
1345void wxLogTrace(const char* mask, const char* formatString, ... );
695d5232 1346void wxVLogTrace(const char* mask, const char* formatString, va_list argPtr);
96d7cc9b
FM
1347//@}
1348
b21126db 1349/** @addtogroup group_funcmacro_log */
ef477678
BP
1350//@{
1351/**
1352 Like wxLogDebug(), trace functions only do something in debug builds and
1353 expand to nothing in the release one. The reason for making it a separate
1354 function is that usually there are a lot of trace messages, so it might
1355 make sense to separate them from other debug messages.
1356
22f24132 1357 @deprecated
ef477678
BP
1358 This version of wxLogTrace() only logs the message if all the bits
1359 corresponding to the @a mask are set in the wxLog trace mask which can be
1360 set by calling wxLog::SetTraceMask(). This version is less flexible than
34085a0d 1361 wxLogTrace(const char*,const char*,...) because it doesn't allow defining
ef477678
BP
1362 the user trace masks easily. This is why it is deprecated in favour of
1363 using string trace masks.
1364
1365 The following bitmasks are defined for wxTraceMask:
1366
1367 @beginDefList
1368 @itemdef{ wxTraceMemAlloc, Trace memory allocation (new/delete) }
1369 @itemdef{ wxTraceMessages, Trace window messages/X callbacks }
1370 @itemdef{ wxTraceResAlloc, Trace GDI resource allocation }
1371 @itemdef{ wxTraceRefCount, Trace various ref counting operations }
1372 @itemdef{ wxTraceOleCalls, Trace OLE method calls (Win32 only) }
1373 @endDefList
1374
1375 @header{wx/log.h}
1376*/
1377void wxLogTrace(wxTraceMask mask, const char* formatString, ... );
1378void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr);
1379//@}
96d7cc9b 1380
b21126db 1381/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1382//@{
1383/**
ef477678
BP
1384 The right functions for debug output. They only do something in debug mode
1385 (when the preprocessor symbol @c __WXDEBUG__ is defined) and expand to
96d7cc9b 1386 nothing in release mode (otherwise).
ef477678
BP
1387
1388 @header{wx/log.h}
96d7cc9b
FM
1389*/
1390void wxLogDebug(const char* formatString, ... );
1391void wxVLogDebug(const char* formatString, va_list argPtr);
1392//@}
1393
b21126db 1394/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1395//@{
1396/**
ef477678
BP
1397 Messages logged by this function will appear in the statusbar of the
1398 @a frame or of the top level application window by default (i.e. when using
96d7cc9b 1399 the second version of the functions).
ef477678 1400
96d7cc9b 1401 If the target frame doesn't have a statusbar, the message will be lost.
ef477678
BP
1402
1403 @header{wx/log.h}
96d7cc9b 1404*/
ef477678
BP
1405void wxLogStatus(wxFrame* frame, const char* formatString, ... );
1406void wxVLogStatus(wxFrame* frame, const char* formatString, va_list argPtr);
96d7cc9b
FM
1407void wxLogStatus(const char* formatString, ... );
1408void wxVLogStatus(const char* formatString, va_list argPtr);
1409//@}
1410
b21126db 1411/** @addtogroup group_funcmacro_log */
96d7cc9b
FM
1412//@{
1413/**
ef477678
BP
1414 Mostly used by wxWidgets itself, but might be handy for logging errors
1415 after system call (API function) failure. It logs the specified message
deed8373 1416 text as well as the last system error code (@e errno or @e GetLastError()
ef477678
BP
1417 depending on the platform) and the corresponding error message. The second
1418 form of this function takes the error code explicitly as the first
1419 argument.
96d7cc9b
FM
1420
1421 @see wxSysErrorCode(), wxSysErrorMsg()
ef477678
BP
1422
1423 @header{wx/log.h}
96d7cc9b
FM
1424*/
1425void wxLogSysError(const char* formatString, ... );
ef477678 1426void wxVLogSysError(const char* formatString, va_list argPtr);
39fb8056
FM
1427//@}
1428
7d9550df
VZ
1429/** @addtogroup group_funcmacro_debug */
1430//@{
1431
1432/**
1433 @def wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
1434
1435 Use this macro to disable logging at debug and trace levels in release
e4431849 1436 build when not using wxIMPLEMENT_APP().
7d9550df
VZ
1437
1438 @see wxDISABLE_DEBUG_SUPPORT(),
1439 wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
1440 @ref overview_debugging
1441
1442 @since 2.9.1
1443
1444 @header{wx/log.h}
1445 */
1446#define wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
1447
1448//@}
1449