wxLog Classes Overview

Classes:


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 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 wxLogXXX() functions. All of them have the same syntax as printf() or 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 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:

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 active at any moment, this is the one used by 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 SetActiveTarget() and it will be used automatically by all subsequent calls to wxLogXXX() functions.

To create a new log target class you only need to derive it from wxLog and implement one (or both) of DoLog() and 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:

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.

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.



wxWidgets logo

[ top ]