interface/wx/msgout.h

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