2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Name: log.h
|
2008-03-10 11:24:38 -04:00
|
|
|
// Purpose: interface of wxLogWindow
|
2008-03-08 08:52:38 -05:00
|
|
|
// Author: wxWidgets team
|
|
|
|
// RCS-ID: $Id$
|
|
|
|
// Licence: wxWindows license
|
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
|
|
/**
|
|
|
|
@class wxLogWindow
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
This class represents a background log window: to be precise, it collects all
|
|
|
|
log messages in the log frame which it manages but also passes them on to the
|
|
|
|
log target which was active at the moment of its creation. This allows, for
|
|
|
|
example, to show all the log messages in a frame but still continue to process
|
|
|
|
them normally by showing the standard log dialog.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
@see wxLogTextCtrl
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxLogWindow : public wxLogInterposer
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Creates the log frame window and starts collecting the messages in it.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 09:43:31 -05:00
|
|
|
@param parent
|
2008-03-09 08:33:59 -04:00
|
|
|
The parent window for the log frame, may be @NULL
|
2008-03-08 09:43:31 -05:00
|
|
|
@param title
|
2008-03-09 08:33:59 -04:00
|
|
|
The title for the log frame
|
2008-03-08 09:43:31 -05:00
|
|
|
@param show
|
2008-03-09 08:33:59 -04:00
|
|
|
@true to show the frame initially (default), otherwise
|
|
|
|
Show() must be called later.
|
2008-03-08 09:43:31 -05:00
|
|
|
@param passToOld
|
2008-03-09 08:33:59 -04:00
|
|
|
@true to process the log messages normally in addition to
|
|
|
|
logging them in the log frame (default), @false to only log them in the
|
|
|
|
log frame.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
wxLogWindow(wxFrame parent, const wxChar title, bool show = true,
|
|
|
|
bool passToOld = true);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the associated log frame window. This may be used to position or resize
|
|
|
|
it but use Show() to show or hide it.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxFrame* GetFrame() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Called if the user closes the window interactively, will not be
|
|
|
|
called if it is destroyed for another reason (such as when program
|
|
|
|
exits).
|
|
|
|
Return @true from here to allow the frame to close, @false to
|
|
|
|
prevent this from happening.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see OnFrameDelete()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
virtual bool OnFrameClose(wxFrame frame);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Called immediately after the log frame creation allowing for
|
|
|
|
any extra initializations.
|
|
|
|
*/
|
|
|
|
virtual void OnFrameCreate(wxFrame frame);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Called right before the log frame is going to be deleted: will
|
|
|
|
always be called unlike OnFrameClose().
|
|
|
|
*/
|
|
|
|
virtual void OnFrameDelete(wxFrame frame);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Shows or hides the frame.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
void Show(bool show = true);
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogInterposerTemp
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
A special version of wxLogChain which uses itself as the
|
|
|
|
new log target. It forwards log messages to the previously installed one in
|
|
|
|
addition to
|
|
|
|
processing them itself. Unlike wxLogInterposer, it doesn't
|
|
|
|
delete the old target which means it can be used to temporarily redirect log
|
|
|
|
output.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
As per wxLogInterposer, this class must be derived from to implement
|
|
|
|
wxLog::DoLog
|
|
|
|
and/or wxLog::DoLogString methods.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
|
|
|
*/
|
|
|
|
class wxLogInterposerTemp : public wxLogChain
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
The default constructor installs this object as the current active log target.
|
|
|
|
*/
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogChain
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
This simple class allows to chain log sinks, that is to install a new sink but
|
|
|
|
keep passing log messages to the old one instead of replacing it completely as
|
|
|
|
wxLog::SetActiveTarget does.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
It is especially useful when you want to divert the logs somewhere (for
|
|
|
|
example to a file or a log window) but also keep showing the error messages
|
|
|
|
using the standard dialogs as wxLogGui does by default.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Example of usage:
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@code
|
|
|
|
wxLogChain *logChain = new wxLogChain(new wxLogStderr);
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
// all the log messages are sent to stderr and also processed as usually
|
|
|
|
...
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
// don't delete logChain directly as this would leave a dangling
|
|
|
|
// pointer as active log target, use SetActiveTarget() instead
|
|
|
|
delete wxLog::SetActiveTarget(...something else or @NULL...);
|
|
|
|
@endcode
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
|
|
|
*/
|
|
|
|
class wxLogChain : public wxLog
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Sets the specified @c logger (which may be @NULL) as the default log
|
|
|
|
target but the log messages are also passed to the previous log target if any.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
wxLogChain(wxLog* logger);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Destroys the previous log target.
|
|
|
|
*/
|
|
|
|
~wxLogChain();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Detaches the old log target so it won't be destroyed when the wxLogChain object
|
|
|
|
is destroyed.
|
|
|
|
*/
|
|
|
|
void DetachOldLog();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the pointer to the previously active log target (which may be @NULL).
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxLog* GetOldLog() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the messages are passed to the previously active log
|
|
|
|
target (default) or @false if PassMessages()
|
|
|
|
had been called.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
bool IsPassingMessages() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
By default, the log messages are passed to the previously active log target.
|
|
|
|
Calling this function with @false parameter disables this behaviour
|
|
|
|
(presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and
|
2008-03-09 08:33:59 -04:00
|
|
|
it can be reenabled by calling it again with @a passMessages set to @true.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
void PassMessages(bool passMessages);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sets another log target to use (may be @NULL). The log target specified
|
|
|
|
in the @ref ctor() constructor or in a previous call to
|
|
|
|
this function is deleted.
|
|
|
|
This doesn't change the old log target value (the one the messages are
|
|
|
|
forwarded to) which still remains the same as was active when wxLogChain
|
|
|
|
object was created.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
void SetLog(wxLog* logger);
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogGui
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
This is the default log target for the GUI wxWidgets applications. It is passed
|
|
|
|
to wxLog::SetActiveTarget at the program
|
|
|
|
startup and is deleted by wxWidgets during the program shut down.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
|
|
|
*/
|
|
|
|
class wxLogGui : public wxLog
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Default constructor.
|
|
|
|
*/
|
|
|
|
wxLogGui();
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogStream
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
This class can be used to redirect the log messages to a C++ stream.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Please note that this class is only available if wxWidgets was compiled with
|
|
|
|
the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on).
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
@see wxLogStderr, wxStreamToTextRedirector
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxLogStream : public wxLog
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Constructs a log target which sends all the log messages to the given
|
|
|
|
output stream. If it is @NULL, the messages are sent to @c cerr.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
wxLogStream(std::ostream ostr = NULL);
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogStderr
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
This class can be used to redirect the log messages to a C file stream (not to
|
|
|
|
be confused with C++ streams). It is the default log target for the non-GUI
|
|
|
|
wxWidgets applications which send all the output to @c stderr.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
@see wxLogStream
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxLogStderr : public wxLog
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Constructs a log target which sends all the log messages to the given
|
|
|
|
@c FILE. If it is @NULL, the messages are sent to @c stderr.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
wxLogStderr(FILE fp = NULL);
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogBuffer
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
wxLogBuffer is a very simple implementation of log sink which simply collects
|
|
|
|
all the logged messages in a string (except the debug messages which are output
|
|
|
|
in the usual way immediately as we're presumably not interested in collecting
|
|
|
|
them for later). The messages from different log function calls are separated
|
|
|
|
by the new lines.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
All the messages collected so far can be shown to the user (and the current
|
2008-03-08 09:43:31 -05:00
|
|
|
buffer cleared) by calling the overloaded wxLogBuffer::Flush
|
2008-03-08 08:52:38 -05:00
|
|
|
method.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{FIXME}
|
|
|
|
*/
|
|
|
|
class wxLogBuffer : public wxLog
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Shows all the messages collected so far to the user (using a message box in the
|
|
|
|
GUI applications or by printing them out to the console in text mode) and
|
|
|
|
clears the internal buffer.
|
|
|
|
*/
|
|
|
|
virtual void Flush();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the current buffer contains. Messages from different log function calls
|
|
|
|
are separated with the new lines in the buffer.
|
|
|
|
The buffer can be cleared by Flush() which will
|
|
|
|
also show the current contents to the user.
|
|
|
|
*/
|
|
|
|
const wxString GetBuffer();
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogInterposer
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
A special version of wxLogChain which uses itself as the
|
|
|
|
new log target. It forwards log messages to the previously installed one in
|
|
|
|
addition to
|
|
|
|
processing them itself.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Unlike wxLogChain which is usually used directly as is,
|
|
|
|
this class must be derived from to implement wxLog::DoLog
|
|
|
|
and/or wxLog::DoLogString methods.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
wxLogInterposer destroys the previous log target in its destructor. If you
|
|
|
|
don't want this to happen, use wxLogInterposerTemp instead.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
|
|
|
*/
|
|
|
|
class wxLogInterposer : public wxLogChain
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
The default constructor installs this object as the current active log target.
|
|
|
|
*/
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogTextCtrl
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Using these target all the log messages can be redirected to a text control.
|
|
|
|
The text control must have been created with @c wxTE_MULTILINE style by the
|
|
|
|
caller previously.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
@see wxTextCtrl, wxStreamToTextRedirector
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxLogTextCtrl : public wxLog
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Constructs a log target which sends all the log messages to the given text
|
2008-03-09 08:33:59 -04:00
|
|
|
control. The @a textctrl parameter cannot be @NULL.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
wxLogTextCtrl(wxTextCtrl textctrl);
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLog
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
wxLog class defines the interface for the @e log targets used by wxWidgets
|
|
|
|
logging functions as explained in the @ref overview_wxlogoverview "wxLog
|
|
|
|
overview".
|
|
|
|
The only situations when you need to directly use this class is when you want
|
|
|
|
to derive your own log target because the existing ones don't satisfy your
|
|
|
|
needs. Another case is if you wish to customize the behaviour of the standard
|
|
|
|
logging classes (all of which respect the wxLog settings): for example, set
|
|
|
|
which trace messages are logged and which are not or change (or even remove
|
|
|
|
completely) the timestamp on the messages.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Otherwise, it is completely hidden behind the @e wxLogXXX() functions and
|
|
|
|
you may not even know about its existence.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
See @ref overview_wxlogoverview "log overview" for the descriptions of wxWidgets
|
|
|
|
logging facilities.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxcore}
|
|
|
|
@category{logging}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
@see wxLog::RemoveTraceMask, wxLog::GetTraceMasks
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-08 09:43:31 -05:00
|
|
|
class wxLog
|
2008-03-08 08:52:38 -05:00
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
2008-03-09 08:33:59 -04:00
|
|
|
Add the @a mask to the list of allowed masks for
|
2008-03-10 11:24:38 -04:00
|
|
|
wxLogTrace().
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see RemoveTraceMask(), GetTraceMasks()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
static void AddTraceMask(const wxString& mask);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Removes all trace masks previously set with
|
|
|
|
AddTraceMask().
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see RemoveTraceMask()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
static void ClearTraceMasks();
|
|
|
|
|
|
|
|
/**
|
|
|
|
The functions below allow some limited customization of wxLog behaviour
|
|
|
|
without writing a new log target class (which, aside of being a matter of
|
|
|
|
several minutes, allows you to do anything you want).
|
|
|
|
The verbose messages are the trace messages which are not disabled in the
|
2008-03-10 11:24:38 -04:00
|
|
|
release mode and are generated by wxLogVerbose(). They
|
2008-03-08 08:52:38 -05:00
|
|
|
are not normally shown to the user because they present little interest, but
|
|
|
|
may be activated, for example, in order to help the user find some program
|
|
|
|
problem.
|
|
|
|
As for the (real) trace messages, their handling depends on the settings of
|
|
|
|
the (application global) @e trace mask. There are two ways to specify it:
|
|
|
|
either by using SetTraceMask() and
|
|
|
|
GetTraceMask() and using
|
2008-03-10 11:24:38 -04:00
|
|
|
wxLogTrace() which takes an integer mask or by using
|
2008-03-08 08:52:38 -05:00
|
|
|
AddTraceMask() for string trace masks.
|
|
|
|
The difference between bit-wise and string trace masks is that a message using
|
|
|
|
integer trace mask will only be logged if all bits of the mask are set in the
|
|
|
|
current mask while a message using string mask will be logged simply if the
|
|
|
|
mask had been added before to the list of allowed ones.
|
|
|
|
For example,
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
will do something only if the current trace mask contains both
|
|
|
|
@c wxTraceRefCount and @c wxTraceOle, but
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
will log the message if it was preceded by
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Using string masks is simpler and allows to easily add custom ones, so this is
|
|
|
|
the preferred way of working with trace messages. The integer trace mask is
|
|
|
|
kept for compatibility and for additional (but very rarely needed) flexibility
|
|
|
|
only.
|
2008-03-10 11:24:38 -04:00
|
|
|
The standard trace masks are given in wxLogTrace()
|
2008-03-08 08:52:38 -05:00
|
|
|
documentation.
|
|
|
|
Finally, the @e wxLog::DoLog() function automatically prepends a time stamp
|
|
|
|
to all the messages. The format of the time stamp may be changed: it can be
|
|
|
|
any string with % specifications fully described in the documentation of the
|
|
|
|
standard @e strftime() function. For example, the default format is
|
|
|
|
"[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] "
|
|
|
|
(without quotes) for the current date. Setting an empty string as the time
|
|
|
|
format disables timestamping of the messages completely.
|
|
|
|
@b NB: Timestamping is disabled for Visual C++ users in debug builds by
|
|
|
|
default because otherwise it would be impossible to directly go to the line
|
|
|
|
from which the log message was generated by simply clicking in the debugger
|
|
|
|
window on the corresponding error message. If you wish to enable it, please use
|
|
|
|
SetTimestamp() explicitly.
|
|
|
|
AddTraceMask()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
RemoveTraceMask()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
ClearTraceMasks()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
GetTraceMasks()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
IsAllowedTraceMask()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
SetVerbose()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
GetVerbose()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
SetTimestamp()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
GetTimestamp()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
SetTraceMask()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
GetTraceMask()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
SetRepetitionCounting()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
GetRepetitionCounting()
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
Disables time stamping of the log messages.
|
|
|
|
This function is new since wxWidgets version 2.9
|
|
|
|
*/
|
|
|
|
void SetTimestamp(const wxString& format);
|
|
|
|
|
|
|
|
/**
|
2008-03-09 08:33:59 -04:00
|
|
|
Called to process the message of the specified severity. @a msg is the text
|
2008-03-08 08:52:38 -05:00
|
|
|
of the message as specified in the call of @e wxLogXXX() function which
|
2008-03-09 08:33:59 -04:00
|
|
|
generated it and @a timestamp is the moment when the message was generated.
|
2008-03-08 08:52:38 -05:00
|
|
|
The base class version prepends the timestamp to the message, adds a prefix
|
|
|
|
corresponding to the log level and then calls
|
|
|
|
DoLogString() with the resulting string.
|
|
|
|
*/
|
|
|
|
virtual void DoLog(wxLogLevel level, const wxString& msg,
|
|
|
|
time_t timestamp);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Called to log the specified string. The timestamp is already included in the
|
|
|
|
string but still passed to this function.
|
|
|
|
A simple implementation may just send the string to @c stdout or, better,
|
|
|
|
@c stderr.
|
|
|
|
*/
|
|
|
|
virtual void DoLogString(const wxString& msg, time_t timestamp);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Instructs wxLog to not create new log targets on the fly if there is none
|
|
|
|
currently. (Almost) for internal use only: it is supposed to be called by the
|
|
|
|
application shutdown code.
|
|
|
|
Note that this function also calls
|
|
|
|
ClearTraceMasks().
|
|
|
|
*/
|
|
|
|
static void DontCreateOnDemand();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Shows all the messages currently in buffer and clears it. If the buffer
|
|
|
|
is already empty, nothing happens.
|
|
|
|
*/
|
|
|
|
virtual void Flush();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Flushes the current log target if any, does nothing if there is none.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see Flush()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
static void FlushActive();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the pointer to the active log target (may be @NULL).
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
static wxLog* GetActiveTarget();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the current log level limit.
|
|
|
|
*/
|
|
|
|
static wxLogLevel GetLogLevel();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns whether the repetition counting mode is enabled.
|
|
|
|
*/
|
|
|
|
static bool GetRepetitionCounting();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the current timestamp format string.
|
|
|
|
*/
|
|
|
|
static const wxString GetTimestamp();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the current trace mask, see Customization() section
|
|
|
|
for details.
|
|
|
|
*/
|
|
|
|
static wxTraceMask GetTraceMask();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the currently allowed list of string trace masks.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see AddTraceMask().
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
static const wxArrayString GetTraceMasks();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns whether the verbose mode is currently active.
|
|
|
|
*/
|
|
|
|
static bool GetVerbose();
|
|
|
|
|
|
|
|
/**
|
|
|
|
The functions in this section work with and manipulate the active log target.
|
|
|
|
The OnLog() is called by the @e wxLogXXX() functions
|
|
|
|
and invokes the DoLog() of the active log target if any.
|
|
|
|
Get/Set methods are used to install/query the current active target and,
|
|
|
|
finally, DontCreateOnDemand() disables the
|
|
|
|
automatic creation of a standard log target if none actually exists. It is
|
|
|
|
only useful when the application is terminating and shouldn't be used in other
|
|
|
|
situations because it may easily lead to a loss of messages.
|
|
|
|
OnLog()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
GetActiveTarget()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
SetActiveTarget()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
DontCreateOnDemand()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Suspend()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Resume()
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
2008-03-09 08:33:59 -04:00
|
|
|
Returns @true if the @a mask is one of allowed masks for
|
2008-03-10 11:24:38 -04:00
|
|
|
wxLogTrace().
|
2008-03-08 08:52:38 -05:00
|
|
|
See also: AddTraceMask(),
|
|
|
|
RemoveTraceMask()
|
|
|
|
*/
|
|
|
|
static bool IsAllowedTraceMask(const wxString& mask);
|
|
|
|
|
|
|
|
/**
|
|
|
|
There are two functions which must be implemented by any derived class to
|
|
|
|
actually process the log messages: DoLog() and
|
|
|
|
DoLogString(). The second function receives a string
|
|
|
|
which just has to be output in some way and the easiest way to write a new log
|
|
|
|
target is to override just this function in the derived class. If more control
|
|
|
|
over the output format is needed, then the first function must be overridden
|
|
|
|
which allows to construct custom messages depending on the log level or even
|
|
|
|
do completely different things depending on the message severity (for example,
|
|
|
|
throw away all messages except warnings and errors, show warnings on the
|
|
|
|
screen and forward the error messages to the user's (or programmer's) cell
|
|
|
|
phone - maybe depending on whether the timestamp tells us if it is day or
|
|
|
|
night in the current time zone).
|
|
|
|
There also functions to support message buffering. Why are they needed?
|
|
|
|
Some of wxLog implementations, most notably the standard wxLogGui class,
|
|
|
|
buffer the messages (for example, to avoid showing the user a zillion of modal
|
|
|
|
message boxes one after another -- which would be really annoying).
|
|
|
|
Flush() shows them all and clears the buffer contents.
|
|
|
|
This function doesn't do anything if the buffer is already empty.
|
|
|
|
Flush()
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
FlushActive()
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
Forwards the message at specified level to the @e DoLog() function of the
|
|
|
|
active log target if there is any, does nothing otherwise.
|
|
|
|
*/
|
|
|
|
static void OnLog(wxLogLevel level, const wxString& message);
|
|
|
|
|
|
|
|
/**
|
2008-03-09 08:33:59 -04:00
|
|
|
Remove the @a mask from the list of allowed masks for
|
2008-03-10 11:24:38 -04:00
|
|
|
wxLogTrace().
|
2008-03-08 08:52:38 -05:00
|
|
|
See also: AddTraceMask()
|
|
|
|
*/
|
|
|
|
static void RemoveTraceMask(const wxString& mask);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Resumes logging previously suspended by a call to
|
|
|
|
Suspend(). All messages logged in the meanwhile will be
|
|
|
|
flushed soon.
|
|
|
|
*/
|
|
|
|
static void Resume();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the specified log target as the active one. Returns the pointer to the
|
|
|
|
previous active log target (may be @NULL). To suppress logging use a new
|
|
|
|
instance of wxLogNull not @NULL. If the active log target is set to @NULL a
|
|
|
|
new default log target will be created when logging occurs.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
static wxLog* SetActiveTarget(wxLog* logtarget);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Specifies that log messages with level logLevel should be ignored
|
|
|
|
and not sent to the active log target.
|
|
|
|
*/
|
|
|
|
static void SetLogLevel(wxLogLevel logLevel);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Enables logging mode in which a log message is logged once, and in case exactly
|
2008-03-08 09:43:31 -05:00
|
|
|
the same message successively repeats one or more times, only the number of
|
2008-03-08 08:52:38 -05:00
|
|
|
repetitions is logged.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
static void SetRepetitionCounting(bool repetCounting = true);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the timestamp format prepended by the default log targets to all
|
|
|
|
messages. The string may contain any normal characters as well as %
|
|
|
|
prefixed format specificators, see @e strftime() manual for details.
|
|
|
|
Passing an empty string to this function disables message time stamping.
|
|
|
|
*/
|
|
|
|
static void SetTimestamp(const wxString& format);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the trace mask, see Customization()
|
|
|
|
section for details.
|
|
|
|
*/
|
|
|
|
static void SetTraceMask(wxTraceMask mask);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Activates or deactivates verbose mode in which the verbose messages are
|
|
|
|
logged as the normal ones instead of being silently dropped.
|
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
static void SetVerbose(bool verbose = true);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Suspends the logging until Resume() is called. Note that
|
|
|
|
the latter must be called the same number of times as the former to undo it,
|
|
|
|
i.e. if you call Suspend() twice you must call Resume() twice as well.
|
|
|
|
Note that suspending the logging means that the log sink won't be be flushed
|
|
|
|
periodically, it doesn't have any effect if the current log target does the
|
|
|
|
logging immediately without waiting for Flush() to be
|
|
|
|
called (the standard GUI log target only shows the log dialog when it is
|
|
|
|
flushed, so Suspend() works as expected with it).
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see Resume(), wxLogNull
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
static void Suspend();
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxLogNull
|
|
|
|
@wxheader{log.h}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
This class allows to temporarily suspend logging. All calls to the log
|
|
|
|
functions during the life time of an object of this class are just ignored.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
In particular, it can be used to suppress the log messages given by wxWidgets
|
|
|
|
itself but it should be noted that it is rarely the best way to cope with this
|
|
|
|
problem as @b all log messages are suppressed, even if they indicate a
|
|
|
|
completely different error than the one the programmer wanted to suppress.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
For instance, the example of the overview:
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@code
|
|
|
|
wxFile file;
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
// 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
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
wxLogMessage("..."); // ok
|
|
|
|
@endcode
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
would be better written as:
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@code
|
|
|
|
wxFile file;
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
// don't try to open file if it doesn't exist, we are prepared to deal with
|
|
|
|
// this ourselves - but all other errors are not expected
|
|
|
|
if ( wxFile::Exists("bar") )
|
|
|
|
{
|
|
|
|
// gives an error message if the file couldn't be opened
|
|
|
|
file.Open("bar");
|
|
|
|
}
|
|
|
|
else
|
|
|
|
{
|
|
|
|
...
|
|
|
|
}
|
|
|
|
@endcode
|
2008-03-08 09:43:31 -05:00
|
|
|
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{logging}
|
|
|
|
*/
|
|
|
|
class wxLogNull : public wxLog
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Suspends logging.
|
|
|
|
*/
|
|
|
|
wxLogNull();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Resumes logging.
|
|
|
|
*/
|
|
|
|
};
|
|
|
|
|
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
// ============================================================================
|
|
|
|
// Global functions/macros
|
|
|
|
// ============================================================================
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
|
|
|
//@{
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
This function shows a message to the user in a safe way and should be safe
|
|
|
|
to call even before the application has been initialized or if it is
|
|
|
|
currently in some other strange state (for example, about to crash). Under
|
|
|
|
Windows this function shows a message box using a native dialog instead of
|
|
|
|
wxMessageBox() (which might be unsafe to call), elsewhere it simply prints
|
|
|
|
the message to the standard output using the title as prefix.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
|
|
|
@param title
|
2008-03-23 02:25:01 -04:00
|
|
|
The title of the message box shown to the user or the prefix of the
|
|
|
|
message string.
|
2008-03-08 09:43:31 -05:00
|
|
|
@param text
|
2008-03-23 02:25:01 -04:00
|
|
|
The text to show to the user.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
@see wxLogFatalError()
|
2008-03-23 02:25:01 -04:00
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-23 02:25:01 -04:00
|
|
|
void wxSafeShowMessage(const wxString& title, const wxString& text);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the error code from the last system call. This function uses
|
|
|
|
@c errno on Unix platforms and @c GetLastError under Win32.
|
2008-03-08 08:52:38 -05:00
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
@see wxSysErrorMsg(), wxLogSysError()
|
2008-03-12 18:18:27 -04:00
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
@header{wx/log.h}
|
|
|
|
*/
|
|
|
|
unsigned long wxSysErrorCode();
|
2008-03-12 18:18:27 -04:00
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/**
|
|
|
|
Returns the error message corresponding to the given system error code. If
|
|
|
|
@a errCode is 0 (default), the last error code (as returned by
|
|
|
|
wxSysErrorCode()) is used.
|
|
|
|
|
|
|
|
@see wxSysErrorCode(), wxLogSysError()
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
|
|
|
*/
|
|
|
|
const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
|
|
|
|
|
|
|
|
//@}
|
|
|
|
|
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
For all normal, informational messages. They also appear in a message box
|
|
|
|
by default (but it can be changed).
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogMessage(const char* formatString, ... );
|
|
|
|
void wxVLogMessage(const char* formatString, va_list argPtr);
|
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
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 could be @c wxLogInfo).
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogVerbose(const char* formatString, ... );
|
|
|
|
void wxVLogVerbose(const char* formatString, va_list argPtr);
|
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
For warnings - they are also normally shown to the user, but don't
|
|
|
|
interrupt the program work.
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogWarning(const char* formatString, ... );
|
|
|
|
void wxVLogWarning(const char* formatString, va_list argPtr);
|
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
Like wxLogError(), but also terminates the program with the exit code 3.
|
|
|
|
Using @e abort() standard function also terminates the program with this
|
|
|
|
exit code.
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogFatalError(const char* formatString, ... );
|
2008-03-23 02:25:01 -04:00
|
|
|
void wxVLogFatalError(const char* formatString, va_list argPtr);
|
2008-03-12 18:18:27 -04:00
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
The functions 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.
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogError(const char* formatString, ... );
|
|
|
|
void wxVLogError(const char* formatString, va_list argPtr);
|
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
Like wxLogDebug(), trace functions only do something in debug builds and
|
|
|
|
expand to nothing in the release one. The reason for making it a separate
|
|
|
|
function is that usually there are a lot of trace messages, so it might
|
|
|
|
make sense to separate them from other debug messages.
|
|
|
|
|
|
|
|
wxLogDebug(const char*,const char*,...) and
|
|
|
|
wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would
|
|
|
|
like to be able to separate trace messages into different categories which
|
|
|
|
can be enabled or disabled with the static functions provided in wxLog.
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogTrace(const char* formatString, ... );
|
|
|
|
void wxVLogTrace(const char* formatString, va_list argPtr);
|
2008-03-23 02:25:01 -04:00
|
|
|
//@}
|
|
|
|
|
|
|
|
/** @ingroup group_funcmacro_log */
|
|
|
|
//@{
|
|
|
|
/**
|
|
|
|
Like wxLogDebug(), trace functions only do something in debug builds and
|
|
|
|
expand to nothing in the release one. The reason for making it a separate
|
|
|
|
function is that usually there are a lot of trace messages, so it might
|
|
|
|
make sense to separate them from other debug messages.
|
|
|
|
|
|
|
|
In this version of wxLogTrace(), trace messages can be separated into
|
|
|
|
different categories and calls using this function only log the message if
|
|
|
|
the given @a mask is currently enabled in wxLog. This lets you selectively
|
|
|
|
trace only some operations and not others by enabling the desired trace
|
|
|
|
masks with wxLog::AddTraceMask() or by setting the
|
|
|
|
@ref overview_envvars "@c WXTRACE environment variable".
|
|
|
|
|
|
|
|
The predefined string trace masks used by wxWidgets are:
|
|
|
|
|
|
|
|
@beginDefList
|
|
|
|
@itemdef{ wxTRACE_MemAlloc, Trace memory allocation (new/delete) }
|
|
|
|
@itemdef{ wxTRACE_Messages, Trace window messages/X callbacks }
|
|
|
|
@itemdef{ wxTRACE_ResAlloc, Trace GDI resource allocation }
|
|
|
|
@itemdef{ wxTRACE_RefCount, Trace various ref counting operations }
|
|
|
|
@itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) }
|
|
|
|
@endDefList
|
|
|
|
|
|
|
|
@note Since both the mask and the format string are strings, this might
|
|
|
|
lead to function signature confusion in some cases: if you intend to
|
|
|
|
call the format string only version of wxLogTrace(), add a "%s"
|
|
|
|
format string parameter and then supply a second string parameter for
|
|
|
|
that "%s", the string mask version of wxLogTrace() will erroneously
|
|
|
|
get called instead, since you are supplying two string parameters to
|
|
|
|
the function. In this case you'll unfortunately have to avoid having
|
|
|
|
two leading string parameters, e.g. by adding a bogus integer (with
|
|
|
|
its "%d" format string).
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
|
|
|
*/
|
|
|
|
void wxLogTrace(const char* mask, const char* formatString, ... );
|
2008-03-12 18:18:27 -04:00
|
|
|
void wxVLogTrace(const char* mask,
|
2008-03-23 02:25:01 -04:00
|
|
|
const char* formatString,
|
|
|
|
va_list argPtr);
|
2008-03-12 18:18:27 -04:00
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
|
|
|
//@{
|
|
|
|
/**
|
|
|
|
Like wxLogDebug(), trace functions only do something in debug builds and
|
|
|
|
expand to nothing in the release one. The reason for making it a separate
|
|
|
|
function is that usually there are a lot of trace messages, so it might
|
|
|
|
make sense to separate them from other debug messages.
|
|
|
|
|
|
|
|
This version of wxLogTrace() only logs the message if all the bits
|
|
|
|
corresponding to the @a mask are set in the wxLog trace mask which can be
|
|
|
|
set by calling wxLog::SetTraceMask(). This version is less flexible than
|
|
|
|
wxLogDebug(const char*,const char*,...) because it doesn't allow defining
|
|
|
|
the user trace masks easily. This is why it is deprecated in favour of
|
|
|
|
using string trace masks.
|
|
|
|
|
|
|
|
The following bitmasks are defined for wxTraceMask:
|
|
|
|
|
|
|
|
@beginDefList
|
|
|
|
@itemdef{ wxTraceMemAlloc, Trace memory allocation (new/delete) }
|
|
|
|
@itemdef{ wxTraceMessages, Trace window messages/X callbacks }
|
|
|
|
@itemdef{ wxTraceResAlloc, Trace GDI resource allocation }
|
|
|
|
@itemdef{ wxTraceRefCount, Trace various ref counting operations }
|
|
|
|
@itemdef{ wxTraceOleCalls, Trace OLE method calls (Win32 only) }
|
|
|
|
@endDefList
|
|
|
|
|
|
|
|
@header{wx/log.h}
|
|
|
|
*/
|
|
|
|
void wxLogTrace(wxTraceMask mask, const char* formatString, ... );
|
|
|
|
void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr);
|
|
|
|
//@}
|
2008-03-12 18:18:27 -04:00
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
The right functions for debug output. They only do something in debug mode
|
|
|
|
(when the preprocessor symbol @c __WXDEBUG__ is defined) and expand to
|
2008-03-12 18:18:27 -04:00
|
|
|
nothing in release mode (otherwise).
|
2008-03-23 02:25:01 -04:00
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogDebug(const char* formatString, ... );
|
|
|
|
void wxVLogDebug(const char* formatString, va_list argPtr);
|
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
Messages logged by this function will appear in the statusbar of the
|
|
|
|
@a frame or of the top level application window by default (i.e. when using
|
2008-03-12 18:18:27 -04:00
|
|
|
the second version of the functions).
|
2008-03-23 02:25:01 -04:00
|
|
|
|
2008-03-12 18:18:27 -04:00
|
|
|
If the target frame doesn't have a statusbar, the message will be lost.
|
2008-03-23 02:25:01 -04:00
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
2008-03-23 02:25:01 -04:00
|
|
|
void wxLogStatus(wxFrame* frame, const char* formatString, ... );
|
|
|
|
void wxVLogStatus(wxFrame* frame, const char* formatString, va_list argPtr);
|
2008-03-12 18:18:27 -04:00
|
|
|
void wxLogStatus(const char* formatString, ... );
|
|
|
|
void wxVLogStatus(const char* formatString, va_list argPtr);
|
|
|
|
//@}
|
|
|
|
|
2008-03-23 02:25:01 -04:00
|
|
|
/** @ingroup group_funcmacro_log */
|
2008-03-12 18:18:27 -04:00
|
|
|
//@{
|
|
|
|
/**
|
2008-03-23 02:25:01 -04:00
|
|
|
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.
|
2008-03-12 18:18:27 -04:00
|
|
|
|
|
|
|
@see wxSysErrorCode(), wxSysErrorMsg()
|
2008-03-23 02:25:01 -04:00
|
|
|
|
|
|
|
@header{wx/log.h}
|
2008-03-12 18:18:27 -04:00
|
|
|
*/
|
|
|
|
void wxLogSysError(const char* formatString, ... );
|
2008-03-23 02:25:01 -04:00
|
|
|
void wxVLogSysError(const char* formatString, va_list argPtr);
|
2008-03-14 11:35:10 -04:00
|
|
|
//@}
|
|
|
|
|