miscellaneous small enhancements

[wxWidgets.git] / docs / doxygen / overviews / log.h

diff --git a/docs/doxygen/overviews/log.h b/docs/doxygen/overviews/log.h
index b02cb5ed1aba00b7a2892490c53fbe8ad41adc04..f39f4cbcc31340b180998a625c6843caa188c1f0 100644 (file)
--- a/docs/doxygen/overviews/log.h
+++ b/docs/doxygen/overviews/log.h
@@ -6,7 +6,7 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

-/*!
+/**

 
 @page overview_log wxLog Classes Overview
 
 
 @page overview_log wxLog Classes Overview
 


@@ -24,6 +24,15 @@ Classes:
 @li wxLogInterposerTemp
 @li wxStreamToTextRedirector
 
 @li wxLogInterposerTemp
 @li wxStreamToTextRedirector
 

+@li @ref overview_log_introduction
+@li @ref overview_log_targets
+@li @ref overview_log_customize
+
+<hr>
+
+
+@section overview_log_introduction Introduction
+

 This is a general overview of logging classes provided by wxWidgets. The word
 logging here has a broad sense, including all of the program output, not only
 non-interactive messages. The logging facilities included in wxWidgets provide
 This is a general overview of logging classes provided by wxWidgets. The word
 logging here has a broad sense, including all of the program output, not only
 non-interactive messages. The logging facilities included in wxWidgets provide


@@ -108,6 +117,9 @@ classes are. Some of advantages in using wxWidgets log functions are:
     error message) will be given to the user together with "high level" message
     about data file writing error.
 
     error message) will be given to the user together with "high level" message
     about data file writing error.
 

+
+@section overview_log_targets Log Targets
+

 After having enumerated all the functions which are normally used to log the
 messages, and why would you want to use them we now describe how all this
 works.
 After having enumerated all the functions which are normally used to log the
 messages, and why would you want to use them we now describe how all this
 works.


@@ -170,5 +182,27 @@ messages somewhere else (for example, to a log file) but also process them as
 normally. For this the wxLogChain, wxLogInterposer, and wxLogInterposerTemp can
 be used.
 
 normally. For this the wxLogChain, wxLogInterposer, and wxLogInterposerTemp can
 be used.
 

+
+@section overview_log_customize Logging Customization
+
+To completely change the logging behaviour you may define a custom log target.
+For example, you could define a class inheriting from wxLog which shows all the
+log messages in some part of your main application window reserved for the
+message output without interrupting the user work flow with modal message
+boxes.
+
+To use your custom log target you may either call wxLog::SetActiveTarget() with
+your custom log object or create a wxAppTraits-derived class and override
+CreateLogTarget() virtual method in it and also override wxApp::CreateTraits()
+to return an instance of your custom traits object. Notice that in the latter
+case you should be prepared for logging messages early during the program
+startup and also during program shutdown so you shouldn't rely on existence of
+the main application window, for example. You can however safely assume that
+GUI is (already/still) available when your log target as used as wxWidgets
+automatically switches to using wxLogStderr if it isn't.
+
+The dialog sample illustrates this approach by defining a custom log target
+customizing the dialog used by wxLogGui for the single messages.
+

 */
 
 */