added images for topic overviews

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

diff --git a/docs/doxygen/overviews/log.h b/docs/doxygen/overviews/log.h
index 68a5ddc6f49531a6717eda39f248fdec53715f10..18ab6bbb9b2676ccaa6e9d32606315c2612bb8a0 100644 (file)
--- a/docs/doxygen/overviews/log.h
+++ b/docs/doxygen/overviews/log.h
@@ -7,29 +7,31 @@
 /////////////////////////////////////////////////////////////////////////////
 
 /*!
 /////////////////////////////////////////////////////////////////////////////
 
 /*!

- 
+

  @page log_overview wxLog classes overview
  @page log_overview wxLog classes overview

- 
+

  Classes: #wxLog,
  Classes: #wxLog,

- 
+

  #wxLogStderr,
  #wxLogStderr,

- 
+

  #wxLogStream,
  #wxLogStream,

- 
+

  #wxLogTextCtrl,
  #wxLogTextCtrl,

- 
+

  #wxLogWindow,
  #wxLogWindow,

- 
+

  #wxLogGui,
  #wxLogGui,

- 
+

  #wxLogNull,
  #wxLogNull,

- 
+
+ #wxLogBuffer,
+

  #wxLogChain,
  #wxLogChain,

- 
+

  #wxLogInterposer,
  #wxLogInterposer,

- 
+

  #wxLogInterposerTemp,
  #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
  #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


@@ -42,8 +44,8 @@
  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:
  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
  @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


@@ -70,7 +72,7 @@
  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
  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
  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


@@ -78,15 +80,15 @@
  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.
  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:
  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.
  @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.


@@ -94,16 +96,16 @@
  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:
  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
  @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
  #wxStreamToTextRedirector class.
  @b Flexibility The output of wxLog functions can be redirected or
  suppressed entirely based on their importance, which is either impossible or


@@ -120,8 +122,8 @@
  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.
  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.
  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.


@@ -142,8 +144,8 @@
  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:
  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,
  @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,


@@ -155,32 +157,34 @@
  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.
  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:
  @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;
  @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
    // 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
    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.
  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.

- 
+

  */
  */

- 
- 
+
+