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 license
   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     Output messages in the best possible way.
 118
 119     Some systems (e.g. MSW) are capable of showing message boxes even from
 120     console programs. If this is the case, this class will use message box if
 121     standard error stream is not available (e.g. running console program not
 122     from console under Windows) or possibly even always, depending on the value
 123     of flags constructor argument.
 124
 125     @library{wxbase}
 126     @category{logging}
 127  */
 128 class wxMessageOutputBest : public wxMessageOutputStderr
 129 {
 130 public:
 131     /**
 132         Create a new message output object.
 133
 134         @param flags
 135             May be either @c wxMSGOUT_PREFER_STDERR (default) meaning that
 136             standard error will be used if it's available (e.g. program is
 137             being run from console under Windows) or @c wxMSGOUT_PREFER_MSGBOX
 138             meaning that a message box will always be used if the current
 139             system supports showing message boxes from console programs
 140             (currently only Windows does).
 141      */
 142     wxMessageOutputBest(wxMessageOutputFlags flags = wxMSGOUT_PREFER_STDERR);
 143 };
 144
 145 /**
 146     Output messages to the system debug output channel.
 147
 148     Under MSW this class outputs messages to the so called debug output. Under
 149     the other systems it simply uses the standard error stream.
 150
 151     @library{wxbase}
 152     @category{logging}
 153  */
 154 class wxMessageOutputDebug : public wxMessageOutputStderr
 155 {
 156 public:
 157     /// Default constructor.
 158     wxMessageOutputDebug();
 159 };
 160
 161 /**
 162     Output messages by showing them in a message box.
 163
 164     This class is only available to GUI applications, unlike all the other
 165     wxMessageOutput-derived classes.
 166
 167     @library{wxcore}
 168     @category{logging}
 169  */
 170 class wxMessageOutputMessageBox : public wxMessageOutput
 171 {
 172 public:
 173     /// Default constructor.
 174     wxMessageOutputMessageBox();
 175 };