Document wxMessageOutput and related classes.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@61461 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/wx/msgout.h b/interface/wx/msgout.h
new file mode 100644 (file)
index 0000000..e444157
--- /dev/null
+++ b/interface/wx/msgout.h
@@ -0,0 +1,175 @@
+/////////////////////////////////////////////////////////////////////////////
+// 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();
+};