interface/wx/msgout.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/msgout.h
   3 // Purpose:     interface of wxMessageOutput and derived classes
   4 // Author:      Vadim Zeitlin
   5 // RCS-ID:      $Id$
   6 // Copyright:   (c) 2009 Vadim Zeitlin
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11     Simple class allowing to write strings to various output channels.
  12
  13     wxMessageOutput is a low-level class and doesn't provide any of the
  14     conveniences of wxLog. It simply allows to write a message to some output
  15     channel: usually file or standard error but possibly also a message box.
  16     While use of wxLog and related functions is preferable in many cases
  17     sometimes this simple interface may be more convenient.
  18
  19     This class itself is an abstract base class for various concrete derived
  20     classes:
  21         - wxMessageOutputStderr
  22         - wxMessageOutputBest
  23         - wxMessageOutputMessageBox
  24         - wxMessageOutputLog
  25
  26     It also provides access to the global message output object which is
  27     created by wxAppTraits::CreateMessageOutput() which creates an object of
  28     class wxMessageOutputStderr in console applications and wxMessageOutputBest
  29     in the GUI ones but may be overridden in user-defined traits class.
  30
  31     Example of using this class:
  32     @code
  33         wxMessageOutputDebug().Printf("name=%s, preparing to greet...", name);
  34         wxMessageOutput::Get()->Printf("Hello, %s!", name);
  35     @endcode
  36
  37     @library{wxbase}
  38     @category{logging}
  39  */
  40 class wxMessageOutput
  41 {
  42 public:
  43     /**
  44         Return the global message output object.
  45
  46         This object is never @NULL while the program is running but may be
  47         @NULL during initialization (before wxApp object is instantiated) or
  48         shutdown.(after wxApp destruction).
  49
  50         @see wxAppTraits::CreateMessageOutput()
  51      */
  52     static wxMessageOutput* Get();
  53
  54     /**
  55         Sets the global message output object.
  56
  57         Using this function may be a simpler alternative to changing the
  58         message output object used for your program than overriding
  59         wxAppTraits::CreateMessageOutput().
  60
  61         Remember to delete the returned pointer or restore it later with
  62         another call to Set().
  63      */
  64     static wxMessageOutput* Set(wxMessageOutput* msgout);
  65
  66     /**
  67         Output a message.
  68
  69         This function uses the same conventions as standard @c printf().
  70      */
  71     void Printf(const wxString& format, ...);
  72
  73     /**
  74         Method called by Printf() to really output the text.
  75
  76         This method is overridden in various derived classes and is also the
  77         one you should override if you implement a custom message output
  78         object.
  79
  80         It may also be called directly instead of Printf(). This is especially
  81         useful when outputting a user-defined string because it can be simply
  82         called with this string instead of using
  83         @code
  84             msgout.Printf("%s", str);
  85         @endcode
  86         (notice that passing user-defined string to Printf() directly is, of
  87         course, a security risk).
  88      */
  89     virtual void Output(const wxString& str) = 0;
  90 };
  91
  92 /**
  93     Output messages to stderr or another STDIO file stream.
  94
  95     Implements wxMessageOutput by using stderr or specified file.
  96
  97     @library{wxbase}
  98     @category{logging}
  99  */
 100 class wxMessageOutputStderr : public wxMessageOutput
 101 {
 102 public:
 103     /**
 104         Create a new message output object associated with standard error
 105         stream by default.
 106
 107         @param fp
 108             Non-null STDIO file stream. Notice that this object does @e not
 109             take ownership of this pointer, i.e. the caller is responsible for
 110             both ensuring that its life-time is great er than life-time of this
 111             object and for deleting it if necessary.
 112      */
 113     wxMessageOutputStderr(FILE *fp = stderr);
 114 };
 115
 116 /**
 117     Flags used with wxMessageOutputBest.
 118
 119     See wxMessageOutputBest::wxMessageOutputBest().
 120  */
 121 enum wxMessageOutputFlags
 122 {
 123     wxMSGOUT_PREFER_STDERR = 0, ///< use stderr if available (this is the default)
 124     wxMSGOUT_PREFER_MSGBOX = 1  ///< always use message box if available
 125 };
 126
 127 /**
 128     Output messages in the best possible way.
 129
 130     Some systems (e.g. MSW) are capable of showing message boxes even from
 131     console programs. If this is the case, this class will use message box if
 132     standard error stream is not available (e.g. running console program not
 133     from console under Windows) or possibly even always, depending on the value
 134     of flags constructor argument.
 135
 136     @library{wxbase}
 137     @category{logging}
 138  */
 139 class wxMessageOutputBest : public wxMessageOutputStderr
 140 {
 141 public:
 142     /**
 143         Create a new message output object.
 144
 145         @param flags
 146             May be either @c wxMSGOUT_PREFER_STDERR (default) meaning that
 147             standard error will be used if it's available (e.g. program is
 148             being run from console under Windows) or @c wxMSGOUT_PREFER_MSGBOX
 149             meaning that a message box will always be used if the current
 150             system supports showing message boxes from console programs
 151             (currently only Windows does).
 152      */
 153     wxMessageOutputBest(wxMessageOutputFlags flags = wxMSGOUT_PREFER_STDERR);
 154 };
 155
 156 /**
 157     Output messages to the system debug output channel.
 158
 159     Under MSW this class outputs messages to the so called debug output. Under
 160     the other systems it simply uses the standard error stream.
 161
 162     @library{wxbase}
 163     @category{logging}
 164  */
 165 class wxMessageOutputDebug : public wxMessageOutputStderr
 166 {
 167 public:
 168     /// Default constructor.
 169     wxMessageOutputDebug();
 170 };
 171
 172 /**
 173     Output messages by showing them in a message box.
 174
 175     This class is only available to GUI applications, unlike all the other
 176     wxMessageOutput-derived classes.
 177
 178     @library{wxcore}
 179     @category{logging}
 180  */
 181 class wxMessageOutputMessageBox : public wxMessageOutput
 182 {
 183 public:
 184     /// Default constructor.
 185     wxMessageOutputMessageBox();
 186 };