/////////////////////////////////////////////////////////////////////////////
/*!
-
+
@page log_overview wxLog classes overview
-
+
Classes: #wxLog,
-
+
#wxLogStderr,
-
+
#wxLogStream,
-
+
#wxLogTextCtrl,
-
+
#wxLogWindow,
-
+
#wxLogGui,
-
+
#wxLogNull,
-
+
+ #wxLogBuffer,
+
#wxLogChain,
-
+
#wxLogInterposer,
-
+
#wxLogInterposerTemp,
-
+
#wxStreamToTextRedirector
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
the same syntax as @e printf() or @e vprintf() , i.e. they take the
format string as the first argument and respectively a variable number of
arguments or a variable argument list pointer. Here are all of them:
-
-
+
+
@b wxLogFatalError which is like @e wxLogError, but also
terminates the program with the exit code 3 (using @e abort() standard
function). Unlike for all the other logging functions, this function can't be
does anything at all in the debug mode (when the preprocessor symbol
__WXDEBUG__ is defined) and expands to nothing in release mode (otherwise).
@b Tip: under Windows, you must either run the program under debugger or
- use a 3rd party program such as #DbgView
+ use a 3rd party program such as #DbgView
to actually see the debug output.
@b wxLogTrace as @b wxLogDebug only does something in debug
build. The reason for making it a separate function from it is that usually
from other debug messages which would be flooded in them. Moreover, the second
version of this function takes a trace mask as the first argument which allows
to further restrict the amount of messages generated.
-
-
+
+
The usage of these functions should be fairly straightforward, however it may
be asked why not use the other logging facilities, such as C standard stdio
functions or C++ streams. The short answer is that they're all very good
generic mechanisms, but are not really adapted for wxWidgets, while the log
classes are. Some of advantages in using wxWidgets log functions are:
-
-
+
+
@b Portability It is a common practice to use @e printf()
statements or cout/cerr C++ streams for writing out some (debug or otherwise)
information.
under Windows where the stdout of GUI programs is not assigned to anything.
Thus, you might view @e wxLogMessage() as a simple substitute for @e printf().
You can also redirect the @e wxLogXXX calls to @e cout by just writing:
-
-
+
+
@code
wxLog *logger=new wxLogStream();
wxLog::SetActiveTarget(logger);
@endcode
-
-
- Finally, there is also a possibility to redirect the output sent to @e cout
- to a #wxTextCtrl by using the
+
+
+ Finally, there is also a possibility to redirect the output sent to @e cout
+ to a #wxTextCtrl by using the
#wxStreamToTextRedirector class.
@b Flexibility The output of wxLog functions can be redirected or
suppressed entirely based on their importance, which is either impossible or
situation, the exact error code (and the corresponding error message) will be
given to the user together with "high level" message about data file writing
error.
-
-
+
+
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.
There are some predefined classes deriving from wxLog and which might be
helpful to see how you can create a new log target class and, of course, may
also be used without any change. There are:
-
-
+
+
@b wxLogStderr This class logs messages to a @e FILE *, using
stderr by default as its name suggests.
@b wxLogStream This class has the same functionality as wxLogStderr,
collects all messages generated by the application and also passes them to the
previous active log target. The log window frame has a menu allowing user to
clear the log, close it completely or save all messages to file.
+ @b wxLogBuffer This target collects all the logged messages in an
+ internal buffer allowing to show them later to the user all at once.
@b wxLogNull The last log class is quite particular: it doesn't do
anything. The objects of this class may be instantiated to (temporarily)
suppress output of @e wxLogXXX() functions. As an example, trying to open a
non-existing file will usually provoke an error message, but if for some
reasons it is unwanted, just use this construction:
-
+
@code
wxFile file;
-
+
// wxFile.Open() normally complains if file can't be opened, we don't want it
{
wxLogNull logNo;
if ( !file.Open("bar") )
... process error ourselves ...
} // ~wxLogNull called, old log sink restored
-
+
wxLogMessage("..."); // ok
@endcode
-
-
-
+
+
+
The log targets can also be combined: for example you may wish to redirect the
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.
-
+
*/
-
-
+
+
projects / wxWidgets.git / blobdiff