X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/36c9828f702fb504b07968703bcd82f04196070a..579e055907e6cc5aa25f9a8fa90b952d8a58159c:/docs/doxygen/overviews/log.h diff --git a/docs/doxygen/overviews/log.h b/docs/doxygen/overviews/log.h index 18ab6bbb9b..f39f4cbcc3 100644 --- a/docs/doxygen/overviews/log.h +++ b/docs/doxygen/overviews/log.h @@ -1,190 +1,208 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: log +// Name: log.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! - - @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 - non-interactive messages. The logging facilities included in wxWidgets provide - the base @e wxLog class which defines the standard interface for a @e log - target as well as several standard implementations of it and a family of - functions to use with them. - First of all, no knowledge of @e wxLog classes is needed to use them. For - this, you should only know about @e wxLogXXX() functions. All of them have - 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 - overridden by a log target. - @b wxLogError is the function to use for error messages, i.e. the - messages that must be shown to the user. The default processing is to pop up a - message box to inform the user about it. - @b wxLogWarning for warnings - they are also normally shown to the - user, but don't interrupt the program work. - @b wxLogMessage is for all normal, informational messages. They also - appear in a message box by default (but it can be changed, see below). - @b wxLogVerbose is for verbose output. Normally, it is suppressed, but - might be activated if the user wishes to know more details about the program - progress (another, but possibly confusing name for the same function is @b wxLogInfo). - @b wxLogStatus is for status messages - they will go into the status - bar of the active or specified (as the first argument) #wxFrame if it has one. - @b wxLogSysError is mostly used by wxWidgets itself, but might be - handy for logging errors after system call (API function) failure. It logs the - specified message text as well as the last system error - code (@e errno or @e ::GetLastError() depending on the platform) and - the corresponding error message. The second form of this function takes the - error code explicitly as the first argument. - @b wxLogDebug is @b the right function for debug output. It only - 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 - 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 - there are a lot of trace messages, so it might make sense to separate them - 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. - Although it works just fine under Unix, these messages go strictly nowhere - 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 - #wxStreamToTextRedirector class. - @b Flexibility The output of wxLog functions can be redirected or - suppressed entirely based on their importance, which is either impossible or - difficult to do with traditional methods. For example, only error messages, or - only error messages and warnings might be logged, filtering out all - informational messages. - @b Completeness Usually, an error message should be presented to the user - when some operation fails. Let's take a quite simple but common case of a file - error: suppose that you're writing your data file on disk and there is not - enough space. The actual error might have been detected inside wxWidgets code - (say, in @e wxFile::Write), so the calling function doesn't really know the - exact reason of the failure, it only knows that the data file couldn't be - written to the disk. However, as wxWidgets uses @e wxLogError() in this - 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. - wxWidgets has the notion of a @e log target: it is just a class deriving - from #wxLog. As such, it implements the virtual functions of - the base class which are called when a message is logged. Only one log target - is @e active at any moment, this is the one used by @e wxLogXXX() - functions. The normal usage of a log object (i.e. object of a class derived - from wxLog) is to install it as the active target with a call to @e SetActiveTarget() and it will be used automatically by all subsequent calls - to @e wxLogXXX() functions. - To create a new log target class you only need to derive it from wxLog and - implement one (or both) of @e DoLog() and @e DoLogString() in it. The - second one is enough if you're happy with the standard wxLog message - formatting (prepending "Error:" or "Warning:", timestamping c) but just want - to send the messages somewhere else. The first one may be overridden to do - whatever you want but you have to distinguish between the different message - types yourself. - 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, - but uses @e ostream and cerr instead of @e FILE * and stderr. - @b wxLogGui This is the standard log target for wxWidgets - applications (it is used by default if you don't do anything) and provides the - most reasonable handling of all types of messages for given platform. - @b wxLogWindow This log target provides a "log console" which - 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. - - */ - +/** + +@page overview_log wxLog Classes Overview + +Classes: +@li wxLog +@li wxLogStderr +@li wxLogStream +@li wxLogTextCtrl +@li wxLogWindow +@li wxLogGui +@li wxLogNull +@li wxLogBuffer +@li wxLogChain +@li wxLogInterposer +@li wxLogInterposerTemp +@li wxStreamToTextRedirector + +@li @ref overview_log_introduction +@li @ref overview_log_targets +@li @ref overview_log_customize + +
+ + +@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 +the base wxLog class which defines the standard interface for a @e log target +as well as several standard implementations of it and a family of functions to +use with them. + +First of all, no knowledge of wxLog classes is needed to use them. For this, +you should only know about @e wxLogXXX() functions. All of them have 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: + +@li wxLogFatalError which is like 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 overridden by a log + target. +@li wxLogError is the function to use for error messages, i.e. the messages + that must be shown to the user. The default processing is to pop up a + message box to inform the user about it. +@li wxLogWarning for warnings. They are also normally shown to the user, but + don't interrupt the program work. +@li wxLogMessage is for all normal, informational messages. They also appear in + a message box by default (but it can be changed, see below). +@li wxLogVerbose is for verbose output. Normally, it is suppressed, but might + be activated if the user wishes to know more details about the program + progress (another, but possibly confusing name for the same function is + wxLogInfo). +@li wxLogStatus is for status messages. They will go into the status bar of the + active or specified (as the first argument) wxFrame if it has one. +@li wxLogSysError is mostly used by wxWidgets itself, but might be handy for + logging errors after system call (API function) failure. It logs the + specified message text as well as the last system error code (@e errno or + ::GetLastError() depending on the platform) and the corresponding error + message. The second form of this function takes the error code explicitly + as the first argument. +@li wxLogDebug is @b the right function for debug output. It only 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 DebugView to actually see the debug output. + - DebugView: http://www.microsoft.com/technet/sysinternals/Miscellaneous/DebugView.mspx +@li wxLogTrace as wxLogDebug only does something in debug build. The reason for + making it a separate function from it is that usually there are a lot of + trace messages, so it might make sense to separate them 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: + +@li @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. Although it works just fine under Unix, these messages go + strictly nowhere under Windows where the stdout of GUI programs is not + assigned to anything. Thus, you might view 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(&cout); + wxLog::SetActiveTarget(logger); + @endcode + Finally, there is also a possibility to redirect the output sent to @e cout + to a wxTextCtrl by using the wxStreamToTextRedirector class. +@li @b Flexibility: The output of wxLog functions can be redirected or + suppressed entirely based on their importance, which is either impossible + or difficult to do with traditional methods. For example, only error + messages, or only error messages and warnings might be logged, filtering + out all informational messages. +@li @b Completeness: Usually, an error message should be presented to the user + when some operation fails. Let's take a quite simple but common case of a + file error: suppose that you're writing your data file on disk and there is + not enough space. The actual error might have been detected inside + wxWidgets code (say, in wxFile::Write), so the calling function doesn't + really know the exact reason of the failure, it only knows that the data + file couldn't be written to the disk. However, as wxWidgets uses + wxLogError() in this 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. + + +@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. + +wxWidgets has the notion of a log target: it is just a class deriving +from wxLog. As such, it implements the virtual functions of the base class +which are called when a message is logged. Only one log target is @e active at +any moment, this is the one used by @e wxLogXXX() functions. The normal usage +of a log object (i.e. object of a class derived from wxLog) is to install it as +the active target with a call to @e SetActiveTarget() and it will be used +automatically by all subsequent calls to @e wxLogXXX() functions. + +To create a new log target class you only need to derive it from wxLog and +implement one (or both) of @e DoLog() and @e DoLogString() in it. The second +one is enough if you're happy with the standard wxLog message formatting +(prepending "Error:" or "Warning:", timestamping @&c) but just want to send +the messages somewhere else. The first one may be overridden to do whatever +you want but you have to distinguish between the different message types +yourself. + +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: + +@li wxLogStderr: This class logs messages to a FILE *, using stderr by + default as its name suggests. +@li wxLogStream: This class has the same functionality as wxLogStderr, but uses + @e ostream and cerr instead of FILE * and stderr. +@li wxLogGui: This is the standard log target for wxWidgets applications (it is + used by default if you don't do anything) and provides the most reasonable + handling of all types of messages for given platform. +@li wxLogWindow: This log target provides a "log console" which 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. +@li wxLogBuffer: This target collects all the logged messages in an internal + buffer allowing to show them later to the user all at once. +@li 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. + + +@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. + +*/