Removed wxPG_EX_LEGACY_VALIDATORS

[wxWidgets.git] / interface / wx / log.h

diff --git a/interface/wx/log.h b/interface/wx/log.h
index bb96ae292640ed8cc2b1a23deaed7ce6baf8e3f7..b4eb85f3c9cef003d8f392722fcc9d0090fce079 100644 (file)
--- a/interface/wx/log.h
+++ b/interface/wx/log.h
@@ -8,7 +8,6 @@
 
 /**
     @class wxLogWindow
 
 /**
     @class wxLogWindow

-    @wxheader{log.h}

 
     This class represents a background log window: to be precise, it collects all
     log messages in the log frame which it manages but also passes them on to the
 
     This class represents a background log window: to be precise, it collects all
     log messages in the log frame which it manages but also passes them on to the


@@ -81,7 +80,6 @@ public:
 
 /**
     @class wxLogInterposerTemp
 
 /**
     @class wxLogInterposerTemp

-    @wxheader{log.h}

 
     A special version of wxLogChain which uses itself as the
     new log target. It forwards log messages to the previously installed one in
 
     A special version of wxLogChain which uses itself as the
     new log target. It forwards log messages to the previously installed one in


@@ -109,7 +107,6 @@ public:
 
 /**
     @class wxLogChain
 
 /**
     @class wxLogChain

-    @wxheader{log.h}

 
     This simple class allows you to chain log sinks, that is to install a new sink but
     keep passing log messages to the old one instead of replacing it completely as
 
     This simple class allows you to chain log sinks, that is to install a new sink but
     keep passing log messages to the old one instead of replacing it completely as


@@ -129,7 +126,7 @@ public:
 
     // don't delete logChain directly as this would leave a dangling
     // pointer as active log target, use SetActiveTarget() instead
 
     // don't delete logChain directly as this would leave a dangling
     // pointer as active log target, use SetActiveTarget() instead

-    delete wxLog::SetActiveTarget(...something else or @NULL...);
+    delete wxLog::SetActiveTarget(...something else or NULL...);

     @endcode
 
     @library{wxbase}
     @endcode
 
     @library{wxbase}


@@ -147,7 +144,7 @@ public:
     /**
         Destroys the previous log target.
     */
     /**
         Destroys the previous log target.
     */

-    ~wxLogChain();
+    virtual ~wxLogChain();

 
     /**
         Detaches the old log target so it won't be destroyed when the wxLogChain object
 
     /**
         Detaches the old log target so it won't be destroyed when the wxLogChain object


@@ -190,13 +187,51 @@ public:
 
 /**
     @class wxLogGui
 
 /**
     @class wxLogGui

-    @wxheader{log.h}

 
 

-    This is the default log target for the GUI wxWidgets applications. It is passed
-    to wxLog::SetActiveTarget at the program
-    startup and is deleted by wxWidgets during the program shut down.
+    This is the default log target for the GUI wxWidgets applications.
+
+    Please see @ref overview_log_customize for explanation of how to change the
+    default log target.
+
+    An object of this class is used by default to show the log messages created
+    by using wxLogMessage(), wxLogError() and other logging functions. It
+    doesn't display the messages logged by them immediately however but
+    accumulates all messages logged during an event handler execution and then
+    shows them all at once when its Flush() method is called during the idle
+    time processing. This has the important advantage of showing only a single
+    dialog to the user even if several messages were logged because of a single
+    error as it often happens (e.g. a low level function could log a message
+    because it failed to open a file resulting in its caller logging another
+    message due to the failure of higher level operation requiring the use of
+    this file). If you need to force the display of all previously logged
+    messages immediately you can use wxLog::FlushActive() to force the dialog
+    display.
+
+    Also notice that if an error message is logged when several informative
+    messages had been already logged before, the informative messages are
+    discarded on the assumption that they are not useful -- and may be
+    confusing and hence harmful -- any more after the error. The warning
+    and error messages are never discarded however and any informational
+    messages logged after the first error one are also kept (as they may
+    contain information about the error recovery). You may override DoLog()
+    method to change this behaviour.
+
+    At any rate, it is possible that that several messages were accumulated
+    before this class Flush() method is called. If this is the case, Flush()
+    uses a custom dialog which shows the last message directly and allows the
+    user to view the previously logged ones by expanding the "Details"
+    wxCollapsiblePane inside it. This custom dialog also provides the buttons
+    for copying the log messages to the clipboard and saving them to a file.
+
+    However if only a single message is present when Flush() is called, just a
+    wxMessageBox() is used to show it. This has the advantage of being closer
+    to the native behaviour but it doesn't give the user any possibility to
+    copy or save the message (except for the recent Windows versions where @c
+    Ctrl-C may be pressed in the message box to copy its contents to the
+    clipboard) so you may want to override DoShowSingleMessage() to customize
+    wxLogGui -- the dialogs sample shows how to do this.

 
 

-    @library{wxbase}
+    @library{wxcore}

     @category{logging}
 */
 class wxLogGui : public wxLog
     @category{logging}
 */
 class wxLogGui : public wxLog


@@ -206,13 +241,144 @@ public:
         Default constructor.
     */
     wxLogGui();
         Default constructor.
     */
     wxLogGui();

+
+    /**
+        Presents the accumulated log messages, if any, to the user.
+
+        This method is called during the idle time and should show any messages
+        accumulated in wxLogGui#m_aMessages field to the user.
+     */
+    virtual void Flush();
+
+protected:
+    /**
+        Returns the appropriate title for the dialog.
+
+        The title is constructed from wxApp::GetAppDisplayName() and the
+        severity string (e.g. "error" or "warning") appropriate for the current
+        wxLogGui#m_bErrors and wxLogGui#m_bWarnings values.
+     */
+    wxString GetTitle() const;
+
+    /**
+        Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on
+        the current maximal severity.
+
+        This value is suitable to be used in the style parameter of
+        wxMessageBox() function.
+     */
+    int GetSeverityIcon() const;
+
+    /**
+        Forgets all the currently stored messages.
+
+        If you override Flush() (and don't call the base class version), you
+        must call this method to avoid messages being logged over and over
+        again.
+     */
+    void Clear();
+
+
+    /**
+        Method called by Flush() to show a single log message.
+
+        This function can be overridden to show the message in a different way.
+        By default a simple wxMessageBox() call is used.
+
+        @param message
+            The message to show (it can contain multiple lines).
+        @param title
+            The suggested title for the dialog showing the message, see
+            GetTitle().
+        @param style
+            One of @c wxICON_XXX constants, see GetSeverityIcon().
+     */
+    virtual void DoShowSingleLogMessage(const wxString& message,
+                                        const wxString& title,
+                                        int style);
+
+    /**
+        Method called by Flush() to show multiple log messages.
+
+        This function can be overridden to show the messages in a different way.
+        By default a special log dialog showing the most recent message and
+        allowing the user to expand it to view the previously logged ones is
+        used.
+
+        @param messages
+            Array of messages to show; it contains more than one element.
+        @param severities
+            Array of message severities containing @c wxLOG_XXX values.
+        @param times
+            Array of time_t values indicating when each message was logged.
+        @param title
+            The suggested title for the dialog showing the message, see
+            GetTitle().
+        @param style
+            One of @c wxICON_XXX constants, see GetSeverityIcon().
+     */
+    virtual void DoShowMultipleLogMessages(const wxArrayString& messages,
+                                           const wxArrayInt& severities,
+                                           const wxArrayLong& times,
+                                           const wxString& title,
+                                           int style);
+
+
+    /**
+        All currently accumulated messages.
+
+        This array may be empty if no messages were logged.
+
+        @see m_aSeverity, m_aTimes
+     */
+    wxArrayString m_aMessages;
+
+    /**
+        The severities of each logged message.
+
+        This array is synchronized with wxLogGui#m_aMessages, i.e. the n-th
+        element of this array corresponds to the severity of the n-th message.
+        The possible severity values are @c wxLOG_XXX constants, e.g.
+        wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.
+     */
+    wxArrayInt m_aSeverity;
+
+    /**
+        The time stamps of each logged message.
+
+        The elements of this array are time_t values corresponding to the time
+        when the message was logged.
+     */
+    wxArrayLong m_aTimes;
+
+    /**
+        True if there any error messages.
+     */
+    bool m_bErrors;
+
+    /**
+        True if there any warning messages.
+
+        If both wxLogGui#m_bErrors and this member are false, there are only
+        informational messages to be shown.
+     */
+    bool m_bWarnings;
+
+    /**
+        True if there any messages to be shown to the user.
+
+        This variable is used instead of simply checking whether
+        wxLogGui#m_aMessages array is empty to allow blocking further calls to
+        Flush() while a log dialog is already being shown, even if the messages
+        array hasn't been emptied yet.
+     */
+    bool m_bHasMessages;

 };
 
 
 
 /**
     @class wxLogStream
 };
 
 
 
 /**
     @class wxLogStream

-    @wxheader{log.h}

 
     This class can be used to redirect the log messages to a C++ stream.
 
 
     This class can be used to redirect the log messages to a C++ stream.
 


@@ -238,7 +404,6 @@ public:
 
 /**
     @class wxLogStderr
 
 /**
     @class wxLogStderr

-    @wxheader{log.h}

 
     This class can be used to redirect the log messages to a C file stream (not to
     be confused with C++ streams). It is the default log target for the non-GUI
 
     This class can be used to redirect the log messages to a C file stream (not to
     be confused with C++ streams). It is the default log target for the non-GUI


@@ -263,7 +428,6 @@ public:
 
 /**
     @class wxLogBuffer
 
 /**
     @class wxLogBuffer

-    @wxheader{log.h}

 
     wxLogBuffer is a very simple implementation of log sink which simply collects
     all the logged messages in a string (except the debug messages which are output
 
     wxLogBuffer is a very simple implementation of log sink which simply collects
     all the logged messages in a string (except the debug messages which are output


@@ -301,7 +465,6 @@ public:
 
 /**
     @class wxLogInterposer
 
 /**
     @class wxLogInterposer

-    @wxheader{log.h}

 
     A special version of wxLogChain which uses itself as the
     new log target. It forwards log messages to the previously installed one in
 
     A special version of wxLogChain which uses itself as the
     new log target. It forwards log messages to the previously installed one in


@@ -330,7 +493,6 @@ public:
 
 /**
     @class wxLogTextCtrl
 
 /**
     @class wxLogTextCtrl

-    @wxheader{log.h}

 
     Using these target all the log messages can be redirected to a text control.
     The text control must have been created with @c wxTE_MULTILINE style by the
 
     Using these target all the log messages can be redirected to a text control.
     The text control must have been created with @c wxTE_MULTILINE style by the


@@ -355,7 +517,6 @@ public:
 
 /**
     @class wxLog
 
 /**
     @class wxLog

-    @wxheader{log.h}

 
     wxLog class defines the interface for the @e log targets used by wxWidgets
     logging functions as explained in the @ref overview_log.
 
     wxLog class defines the interface for the @e log targets used by wxWidgets
     logging functions as explained in the @ref overview_log.


@@ -504,14 +665,11 @@ public:
     */
     static void ClearTraceMasks();
 
     */
     static void ClearTraceMasks();
 

-    */
-
-

     /**
         Disables time stamping of the log messages.
         This function is new since wxWidgets version 2.9
     */
     /**
         Disables time stamping of the log messages.
         This function is new since wxWidgets version 2.9
     */

-    void SetTimestamp(const wxString& format);
+    static void SetTimestamp(const wxString& format);

 
     /**
         Called to process the message of the specified severity. @a msg is the text
 
     /**
         Called to process the message of the specified severity. @a msg is the text


@@ -639,17 +797,18 @@ public:
     static void RemoveTraceMask(const wxString& mask);
 
     /**
     static void RemoveTraceMask(const wxString& mask);
 
     /**

-        Resumes logging previously suspended by a call to
-        Suspend(). All messages logged in the meanwhile will be
-        flushed soon.
+        Resumes logging previously suspended by a call to Suspend().
+        All messages logged in the meanwhile will be flushed soon.

     */
     static void Resume();
 
     /**
     */
     static void Resume();
 
     /**

-        Sets the specified log target as the active one. Returns the pointer to the
-        previous active log target (may be @NULL).  To suppress logging use a new
-        instance of wxLogNull not @NULL.  If the active log target is set to @NULL a
-        new default log target will be created when logging occurs.
+        Sets the specified log target as the active one.
+
+        Returns the pointer to the previous active log target (may be @NULL).
+        To suppress logging use a new instance of wxLogNull not @NULL.  If the
+        active log target is set to @NULL a new default log target will be
+        created when logging occurs.

     */
     static wxLog* SetActiveTarget(wxLog* logtarget);
 
     */
     static wxLog* SetActiveTarget(wxLog* logtarget);
 


@@ -705,7 +864,6 @@ public:
 
 /**
     @class wxLogNull
 
 /**
     @class wxLogNull

-    @wxheader{log.h}

 
     This class allows you to temporarily suspend logging. All calls to the log
     functions during the life time of an object of this class are just ignored.
 
     This class allows you to temporarily suspend logging. All calls to the log
     functions during the life time of an object of this class are just ignored.