wxWidgets/interface/wx/msgout.h

176 lines
5.6 KiB
C
Raw Normal View History

/////////////////////////////////////////////////////////////////////////////
// Name: wx/msgout.h
// Purpose: interface of wxMessageOutput and derived classes
// Author: Vadim Zeitlin
// RCS-ID: $Id$
// Copyright: (c) 2009 Vadim Zeitlin
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
Simple class allowing to write strings to various output channels.
wxMessageOutput is a low-level class and doesn't provide any of the
conveniences of wxLog. It simply allows to write a message to some output
channel: usually file or standard error but possibly also a message box.
While use of wxLog and related functions is preferable in many cases
sometimes this simple interface may be more convenient.
This class itself is an abstract base class for various concrete derived
classes:
- wxMessageOutputStderr
- wxMessageOutputBest
- wxMessageOutputMessageBox
- wxMessageOutputLog
It also provides access to the global message output object which is
created by wxAppTraits::CreateMessageOutput() which creates an object of
class wxMessageOutputStderr in console applications and wxMessageOutputBest
in the GUI ones but may be overridden in user-defined traits class.
Example of using this class:
@code
wxMessageOutputDebug().Printf("name=%s, preparing to greet...", name);
wxMessageOutput::Get()->Printf("Hello, %s!", name);
@endcode
@library{wxbase}
@category{logging}
*/
class wxMessageOutput
{
public:
/**
Return the global message output object.
This object is never @NULL while the program is running but may be
@NULL during initialization (before wxApp object is instantiated) or
shutdown.(after wxApp destruction).
@see wxAppTraits::CreateMessageOutput()
*/
static wxMessageOutput* Get();
/**
Sets the global message output object.
Using this function may be a simpler alternative to changing the
message output object used for your program than overriding
wxAppTraits::CreateMessageOutput().
Remember to delete the returned pointer or restore it later with
another call to Set().
*/
static wxMessageOutput* Set(wxMessageOutput* msgout);
/**
Output a message.
This function uses the same conventions as standard @c printf().
*/
void Printf(const wxString& format, ...);
/**
Method called by Printf() to really output the text.
This method is overridden in various derived classes and is also the
one you should override if you implement a custom message output
object.
It may also be called directly instead of Printf(). This is especially
useful when outputting a user-defined string because it can be simply
called with this string instead of using
@code
msgout.Printf("%s", str);
@endcode
(notice that passing user-defined string to Printf() directly is, of
course, a security risk).
*/
virtual void Output(const wxString& str) = 0;
};
/**
Output messages to stderr or another STDIO file stream.
Implements wxMessageOutput by using stderr or specified file.
@library{wxbase}
@category{logging}
*/
class wxMessageOutputStderr : public wxMessageOutput
{
public:
/**
Create a new message output object associated with standard error
stream by default.
@param fp
Non-null STDIO file stream. Notice that this object does @e not
take ownership of this pointer, i.e. the caller is responsible for
both ensuring that its life-time is great er than life-time of this
object and for deleting it if necessary.
*/
wxMessageOutputStderr(FILE *fp = stderr);
};
/**
Output messages in the best possible way.
Some systems (e.g. MSW) are capable of showing message boxes even from
console programs. If this is the case, this class will use message box if
standard error stream is not available (e.g. running console program not
from console under Windows) or possibly even always, depending on the value
of flags constructor argument.
@library{wxbase}
@category{logging}
*/
class wxMessageOutputBest : public wxMessageOutputStderr
{
public:
/**
Create a new message output object.
@param flags
May be either @c wxMSGOUT_PREFER_STDERR (default) meaning that
standard error will be used if it's available (e.g. program is
being run from console under Windows) or @c wxMSGOUT_PREFER_MSGBOX
meaning that a message box will always be used if the current
system supports showing message boxes from console programs
(currently only Windows does).
*/
wxMessageOutputBest(wxMessageOutputFlags flags = wxMSGOUT_PREFER_STDERR);
};
/**
Output messages to the system debug output channel.
Under MSW this class outputs messages to the so called debug output. Under
the other systems it simply uses the standard error stream.
@library{wxbase}
@category{logging}
*/
class wxMessageOutputDebug : public wxMessageOutputStderr
{
public:
/// Default constructor.
wxMessageOutputDebug();
};
/**
Output messages by showing them in a message box.
This class is only available to GUI applications, unlike all the other
wxMessageOutput-derived classes.
@library{wxcore}
@category{logging}
*/
class wxMessageOutputMessageBox : public wxMessageOutput
{
public:
/// Default constructor.
wxMessageOutputMessageBox();
};