+\section{Log classes overview}\label{wxlogoverview}
+
+Classes: \helpref{wxLog}wxlog, \helpref{wxLogStderr}wxlogstderr,
+\helpref{wxLogOstream}wxlogostream, \helpref{wxLogTextCtrl}wxlogtextctrl,
+\helpref{wxLogWindow}{wxlogwindow}, \helpref{wxLogGui}{wxloggui},
+\helpref{wxLogNull}{wxlognull}
+
+This is a general overview of logging classes provided by wxWindows. The word
+logging here has a broad sense, including all of the program output, not only
+non interactive messages. The logging facilities included in wxWindows provide
+the base {\it wxLog} class which defines the standard interface for a {\it 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 {\it wxLog} classes is needed to use them. For
+this, you should only know about {\it wxLogXXX()} functions. All of them have
+the same syntax as {\it printf()}, i.e. they take the format string as the
+first argument and a variable number of arguments. Here are all of them:
+\begin{itemize}\itemsep=0pt
+\item{\bf wxLogFatalError} which is like {\it wxLogError}, but also
+terminates the program with the exit code 3 (using {\it abort()} standard
+function also terminates the program with this exit code).
+
+\item{\bf 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.
+
+\item{\bf wxLogWarning} for warnings - they are also normally shown to the
+user, but don't interrupt the program work.
+
+\item{\bf wxLogMessage} is for all normal, informational messages. They also
+appear in a message box by default (but it can be changed, see below). Notice
+that the standard behaviour is to not show informational messages if there are
+any errors later - the logic being that the later error messages make the
+informational messages preceding them meaningless.
+
+\item{\bf wxLogVerbose} is for verbose output. Normally, it's 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 {\bf
+wxLogInfo}
+
+\item{\bf wxLogStatus} is for status messages - they will go into the status
+bar of the active or specified (as the first argument)
+\helpref{wxFrame}{wxframe} if it has one.
+
+\item{\bf wxLogSysError} is mostly used by wxWindows 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 ({\it errno} or
+{\it ::GetLastError()} depending on the platform) and the corresponding error
+message. The second form of this function takes the error code explitly as the
+first argument.
+
+\item{\bf wxLogDebug} is {\bf 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).
+
+\item{\bf wxLogTrace} as {\bf 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.
+
+\end{itemize}
+
+% VZ: Julian, am I pushing too much here?
+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 wxWindows, while the log
+classes are. Some of advantages in using wxWindows log functions are:
+\begin{itemize}\itemsep=0pt
+
+\item{Portability} It's a common practice to use {\it 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 nowever
+under Windows where the stdout of GUI programs is not assigned to anything.
+Thus, you might view {\it wxLogMessage()} as a simple substitute for {\it
+printf()}.
+
+\item{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.
+
+\item{Comlpeteness} 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 wxWindows code
+(say, in {\it 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 wxWindows uses {\it 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.
+
+\end{itemize}
+
+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.
+
+wxWindows has the notion of a {\it log target}: it's just a class deriving
+from \helpref{wxLog}{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 {\it active} at any moment, this is the one used by \it{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 {\it
+SetActiveTarget()} and it will be used automatically by all subsequent calls
+to {\it wxLogXXX()} functions.
+
+To create a new log target class you only need to derive it from wxLog and
+implement one (or both) of {\it DoLog()} and {\it 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:
+\begin{itemize}\itemsep=0pt
+\item{\bf wxLogStderr} This class logs messages to a {\it FILE *}, using
+stderr by default as its name suggests.
+
+\item{\bf wxLogStream} This class has the same functionality as wxLogStderr,
+but uses {\it ostream} and cerr instead of {\it FILE *} and stderr.
+
+\item{\bf wxLogGui} This is the standard log target for wxWindows
+applications (it's used by default if you don't do anything) and provides the
+most reasonable handling of all types of messages for given platform.
+
+\item{\bf 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.
+
+\item{\bf 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 {\it wxLogXXX()} functions. As an example, trying to open a
+non-existing file will usually provoke an error message, but if you for some
+reason it's unwanted, just use this construction:
+\begin{verbatim}
+ 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
+\end{verbatim}
+
+\end{itemize}
projects / wxWidgets.git / commitdiff
