interface/wx/generic/logg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        logg.h
   3 // Purpose:     interface of GUI wxLog* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxLogWindow
  12
  13     This class represents a background log window: to be precise, it collects all
  14     log messages in the log frame which it manages but also passes them on to the
  15     log target which was active at the moment of its creation. This allows you, for
  16     example, to show all the log messages in a frame but still continue to process
  17     them normally by showing the standard log dialog.
  18
  19     @library{wxcore}
  20     @category{logging}
  21     @header{wx/log.h}
  22
  23     @see wxLogTextCtrl
  24 */
  25 class wxLogWindow : public wxLogInterposer
  26 {
  27 public:
  28     /**
  29         Creates the log frame window and starts collecting the messages in it.
  30
  31         @param pParent
  32             The parent window for the log frame, may be @NULL
  33         @param szTitle
  34             The title for the log frame
  35         @param show
  36             @true to show the frame initially (default), otherwise
  37             Show() must be called later.
  38         @param passToOld
  39             @true to process the log messages normally in addition to logging them
  40             in the log frame (default), @false to only log them in the log frame.
  41             Note that if no targets were set using wxLog::SetActiveTarget() then
  42             wxLogWindow simply becomes the active one and messages won't be passed
  43             to other targets.
  44     */
  45     wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true,
  46                 bool passToOld = true);
  47
  48     /**
  49         Returns the associated log frame window. This may be used to position or resize
  50         it but use Show() to show or hide it.
  51     */
  52     wxFrame* GetFrame() const;
  53
  54     /**
  55         Called if the user closes the window interactively, will not be
  56         called if it is destroyed for another reason (such as when program
  57         exits).
  58
  59         Return @true from here to allow the frame to close, @false to
  60         prevent this from happening.
  61
  62         @see OnFrameDelete()
  63     */
  64     virtual bool OnFrameClose(wxFrame* frame);
  65
  66     /**
  67         Called immediately after the log frame creation allowing for
  68         any extra initializations.
  69     */
  70     virtual void OnFrameCreate(wxFrame* frame);
  71
  72     /**
  73         Called right before the log frame is going to be deleted: will
  74         always be called unlike OnFrameClose().
  75     */
  76     virtual void OnFrameDelete(wxFrame* frame);
  77
  78     /**
  79         Shows or hides the frame.
  80     */
  81     void Show(bool show = true);
  82 };
  83
  84
  85
  86 /**
  87     @class wxLogGui
  88
  89     This is the default log target for the GUI wxWidgets applications.
  90
  91     Please see @ref overview_log_customize for explanation of how to change the
  92     default log target.
  93
  94     An object of this class is used by default to show the log messages created
  95     by using wxLogMessage(), wxLogError() and other logging functions. It
  96     doesn't display the messages logged by them immediately however but
  97     accumulates all messages logged during an event handler execution and then
  98     shows them all at once when its Flush() method is called during the idle
  99     time processing. This has the important advantage of showing only a single
 100     dialog to the user even if several messages were logged because of a single
 101     error as it often happens (e.g. a low level function could log a message
 102     because it failed to open a file resulting in its caller logging another
 103     message due to the failure of higher level operation requiring the use of
 104     this file). If you need to force the display of all previously logged
 105     messages immediately you can use wxLog::FlushActive() to force the dialog
 106     display.
 107
 108     Also notice that if an error message is logged when several informative
 109     messages had been already logged before, the informative messages are
 110     discarded on the assumption that they are not useful -- and may be
 111     confusing and hence harmful -- any more after the error. The warning
 112     and error messages are never discarded however and any informational
 113     messages logged after the first error one are also kept (as they may
 114     contain information about the error recovery). You may override DoLog()
 115     method to change this behaviour.
 116
 117     At any rate, it is possible that that several messages were accumulated
 118     before this class Flush() method is called. If this is the case, Flush()
 119     uses a custom dialog which shows the last message directly and allows the
 120     user to view the previously logged ones by expanding the "Details"
 121     wxCollapsiblePane inside it. This custom dialog also provides the buttons
 122     for copying the log messages to the clipboard and saving them to a file.
 123
 124     However if only a single message is present when Flush() is called, just a
 125     wxMessageBox() is used to show it. This has the advantage of being closer
 126     to the native behaviour but it doesn't give the user any possibility to
 127     copy or save the message (except for the recent Windows versions where @c
 128     Ctrl-C may be pressed in the message box to copy its contents to the
 129     clipboard) so you may want to override DoShowSingleLogMessage() to
 130     customize wxLogGui -- the dialogs sample shows how to do this.
 131
 132     @library{wxcore}
 133     @category{logging}
 134     @header{wx/log.h}
 135 */
 136 class wxLogGui : public wxLog
 137 {
 138 public:
 139     /**
 140         Default constructor.
 141     */
 142     wxLogGui();
 143
 144     /**
 145         Presents the accumulated log messages, if any, to the user.
 146
 147         This method is called during the idle time and should show any messages
 148         accumulated in wxLogGui#m_aMessages field to the user.
 149      */
 150     virtual void Flush();
 151
 152 protected:
 153     /**
 154         Returns the appropriate title for the dialog.
 155
 156         The title is constructed from wxApp::GetAppDisplayName() and the
 157         severity string (e.g. "error" or "warning") appropriate for the current
 158         wxLogGui#m_bErrors and wxLogGui#m_bWarnings values.
 159      */
 160     wxString GetTitle() const;
 161
 162     /**
 163         Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on
 164         the current maximal severity.
 165
 166         This value is suitable to be used in the style parameter of
 167         wxMessageBox() function.
 168      */
 169     int GetSeverityIcon() const;
 170
 171     /**
 172         Forgets all the currently stored messages.
 173
 174         If you override Flush() (and don't call the base class version), you
 175         must call this method to avoid messages being logged over and over
 176         again.
 177      */
 178     void Clear();
 179
 180
 181     /**
 182         All currently accumulated messages.
 183
 184         This array may be empty if no messages were logged.
 185
 186         @see m_aSeverity, m_aTimes
 187      */
 188     wxArrayString m_aMessages;
 189
 190     /**
 191         The severities of each logged message.
 192
 193         This array is synchronized with wxLogGui#m_aMessages, i.e. the n-th
 194         element of this array corresponds to the severity of the n-th message.
 195         The possible severity values are @c wxLOG_XXX constants, e.g.
 196         wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.
 197      */
 198     wxArrayInt m_aSeverity;
 199
 200     /**
 201         The time stamps of each logged message.
 202
 203         The elements of this array are time_t values corresponding to the time
 204         when the message was logged.
 205      */
 206     wxArrayLong m_aTimes;
 207
 208     /**
 209         True if there any error messages.
 210      */
 211     bool m_bErrors;
 212
 213     /**
 214         True if there any warning messages.
 215
 216         If both wxLogGui#m_bErrors and this member are false, there are only
 217         informational messages to be shown.
 218      */
 219     bool m_bWarnings;
 220
 221     /**
 222         True if there any messages to be shown to the user.
 223
 224         This variable is used instead of simply checking whether
 225         wxLogGui#m_aMessages array is empty to allow blocking further calls to
 226         Flush() while a log dialog is already being shown, even if the messages
 227         array hasn't been emptied yet.
 228      */
 229     bool m_bHasMessages;
 230
 231 private:
 232     /**
 233         Method called by Flush() to show a single log message.
 234
 235         This function can be overridden to show the message in a different way.
 236         By default a simple wxMessageBox() call is used.
 237
 238         @param message
 239             The message to show (it can contain multiple lines).
 240         @param title
 241             The suggested title for the dialog showing the message, see
 242             GetTitle().
 243         @param style
 244             One of @c wxICON_XXX constants, see GetSeverityIcon().
 245      */
 246     virtual void DoShowSingleLogMessage(const wxString& message,
 247                                         const wxString& title,
 248                                         int style);
 249
 250     /**
 251         Method called by Flush() to show multiple log messages.
 252
 253         This function can be overridden to show the messages in a different way.
 254         By default a special log dialog showing the most recent message and
 255         allowing the user to expand it to view the previously logged ones is
 256         used.
 257
 258         @param messages
 259             Array of messages to show; it contains more than one element.
 260         @param severities
 261             Array of message severities containing @c wxLOG_XXX values.
 262         @param times
 263             Array of time_t values indicating when each message was logged.
 264         @param title
 265             The suggested title for the dialog showing the message, see
 266             GetTitle().
 267         @param style
 268             One of @c wxICON_XXX constants, see GetSeverityIcon().
 269      */
 270     virtual void DoShowMultipleLogMessages(const wxArrayString& messages,
 271                                            const wxArrayInt& severities,
 272                                            const wxArrayLong& times,
 273                                            const wxString& title,
 274                                            int style);
 275 };
 276
 277
 278
 279 /**
 280     @class wxLogTextCtrl
 281
 282     Using these target all the log messages can be redirected to a text control.
 283     The text control must have been created with @c wxTE_MULTILINE style by the
 284     caller previously.
 285
 286     @library{wxcore}
 287     @category{logging}
 288     @header{wx/log.h}
 289
 290     @see wxTextCtrl, wxStreamToTextRedirector
 291 */
 292 class wxLogTextCtrl : public wxLog
 293 {
 294 public:
 295     /**
 296         Constructs a log target which sends all the log messages to the given text
 297         control. The @a textctrl parameter cannot be @NULL.
 298     */
 299     wxLogTextCtrl(wxTextCtrl* pTextCtrl);
 300 };