From: Bryan Petty Date: Sun, 23 Mar 2008 06:25:01 +0000 (+0000) Subject: Finished review/fixes of Logging category of functions and macros. X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/ef477678f2ab47f7aa0861952502aae347f9f088 Finished review/fixes of Logging category of functions and macros. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52726 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/doxygen/groups/funcmacro_log.h b/docs/doxygen/groups/funcmacro_log.h index bb2aee3e9b..357049742d 100644 --- a/docs/doxygen/groups/funcmacro_log.h +++ b/docs/doxygen/groups/funcmacro_log.h @@ -18,7 +18,5 @@ the beginning of the program). Related Overviews: @ref overview_log -@header{wx/log.h} - */ diff --git a/interface/log.h b/interface/log.h index c6af51ae39..d19674a90d 100644 --- a/interface/log.h +++ b/interface/log.h @@ -756,192 +756,253 @@ public: // Global functions/macros // ============================================================================ +/** @ingroup group_funcmacro_log */ +//@{ + /** - This function shows a message to the user in a safe way and should be safe to - call even before the application has been initialized or if it is currently in - some other strange state (for example, about to crash). Under Windows this - function shows a message box using a native dialog instead of - wxMessageBox() (which might be unsafe to call), elsewhere - it simply prints the message to the standard output using the title as prefix. + This function shows a message to the user in a safe way and should be safe + to call even before the application has been initialized or if it is + currently in some other strange state (for example, about to crash). Under + Windows this function shows a message box using a native dialog instead of + wxMessageBox() (which might be unsafe to call), elsewhere it simply prints + the message to the standard output using the title as prefix. @param title - The title of the message box shown to the user or the prefix - of the message string + The title of the message box shown to the user or the prefix of the + message string. @param text - The text to show to the user + The text to show to the user. @see wxLogFatalError() + + @header{wx/log.h} */ -void wxSafeShowMessage(const wxString& title, - const wxString& text); +void wxSafeShowMessage(const wxString& title, const wxString& text); + +/** + Returns the error code from the last system call. This function uses + @c errno on Unix platforms and @c GetLastError under Win32. + @see wxSysErrorMsg(), wxLogSysError() + @header{wx/log.h} +*/ +unsigned long wxSysErrorCode(); +/** + Returns the error message corresponding to the given system error code. If + @a errCode is 0 (default), the last error code (as returned by + wxSysErrorCode()) is used. + + @see wxSysErrorCode(), wxLogSysError() + + @header{wx/log.h} +*/ +const wxChar* wxSysErrorMsg(unsigned long errCode = 0); + +//@} + +/** @ingroup group_funcmacro_log */ //@{ /** - For all normal, informational messages. They also appear in a message box by - default (but it can be changed). + For all normal, informational messages. They also appear in a message box + by default (but it can be changed). + + @header{wx/log.h} */ void wxLogMessage(const char* formatString, ... ); void wxVLogMessage(const char* formatString, va_list argPtr); //@} +/** @ingroup group_funcmacro_log */ //@{ /** - For verbose output. Normally, it is suppressed, but - might be activated if the user wishes to know more details about the program - progress (another, but possibly confusing name for the same function is @b - wxLogInfo). + For verbose output. Normally, it is suppressed, but might be activated if + the user wishes to know more details about the program progress (another, + but possibly confusing name for the same function could be @c wxLogInfo). + + @header{wx/log.h} */ void wxLogVerbose(const char* formatString, ... ); void wxVLogVerbose(const char* formatString, va_list argPtr); //@} +/** @ingroup group_funcmacro_log */ //@{ /** - For warnings - they are also normally shown to the user, but don't interrupt - the program work. + For warnings - they are also normally shown to the user, but don't + interrupt the program work. + + @header{wx/log.h} */ void wxLogWarning(const char* formatString, ... ); void wxVLogWarning(const char* formatString, va_list argPtr); //@} +/** @ingroup group_funcmacro_log */ //@{ /** - Like wxLogError(), but also - terminates the program with the exit code 3. Using @e abort() standard - function also terminates the program with this exit code. + Like wxLogError(), but also terminates the program with the exit code 3. + Using @e abort() standard function also terminates the program with this + exit code. + + @header{wx/log.h} */ void wxLogFatalError(const char* formatString, ... ); -void wxVLogFatalError(const char* formatString, - va_list argPtr); +void wxVLogFatalError(const char* formatString, va_list argPtr); //@} +/** @ingroup group_funcmacro_log */ //@{ /** - The functions to use for error messages, i.e. the messages that must be shown - to the user. The default processing is to pop up a message box to inform the - user about it. + The functions to use for error messages, i.e. the messages that must be + shown to the user. The default processing is to pop up a message box to + inform the user about it. + + @header{wx/log.h} */ void wxLogError(const char* formatString, ... ); void wxVLogError(const char* formatString, va_list argPtr); //@} - +/** @ingroup group_funcmacro_log */ //@{ /** - As @b wxLogDebug, trace functions only do something in debug build and - expand to nothing in the release one. The reason for making - it a separate function from it is that usually there are a lot of trace - messages, so it might make sense to separate them from other debug messages. - The trace messages also usually can be separated into different categories and - the second and third versions of this function only log the message if the - @a mask which it has is currently enabled in wxLog. This - allows to selectively trace only some operations and not others by changing - the value of the trace mask (possible during the run-time). - For the second function (taking a string mask), the message is logged only if - the mask has been previously enabled by the call to - wxLog::AddTraceMask or by setting - @ref overview_envvars "@c WXTRACE environment variable". - The predefined string trace masks - used by wxWidgets are: - wxTRACE_MemAlloc: trace memory allocation (new/delete) - wxTRACE_Messages: trace window messages/X callbacks - wxTRACE_ResAlloc: trace GDI resource allocation - wxTRACE_RefCount: trace various ref counting operations - wxTRACE_OleCalls: trace OLE method calls (Win32 only) - @b Caveats: since both the mask and the format string are strings, - this might lead to function signature confusion in some cases: - if you intend to call the format string only version of wxLogTrace, - then add a %s format string parameter and then supply a second string parameter - for that %s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function. - In this case you'll unfortunately have to avoid having two leading - string parameters, e.g. by adding a bogus integer (with its %d format string). - The third version of the function only logs the message if all the bits - corresponding to the @a mask are set in the wxLog trace mask which can be - set by wxLog::SetTraceMask. This version is less - flexible than the previous one because it doesn't allow defining the user - trace masks easily - this is why it is deprecated in favour of using string - trace masks. - wxTraceMemAlloc: trace memory allocation (new/delete) - wxTraceMessages: trace window messages/X callbacks - wxTraceResAlloc: trace GDI resource allocation - wxTraceRefCount: trace various ref counting operations - wxTraceOleCalls: trace OLE method calls (Win32 only) + Like wxLogDebug(), trace functions only do something in debug builds and + expand to nothing in the release one. The reason for making it a separate + function is that usually there are a lot of trace messages, so it might + make sense to separate them from other debug messages. + + wxLogDebug(const char*,const char*,...) and + wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would + like to be able to separate trace messages into different categories which + can be enabled or disabled with the static functions provided in wxLog. + + @header{wx/log.h} */ void wxLogTrace(const char* formatString, ... ); void wxVLogTrace(const char* formatString, va_list argPtr); -void wxLogTrace(const char* mask, const char* formatString, - ... ); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + Like wxLogDebug(), trace functions only do something in debug builds and + expand to nothing in the release one. The reason for making it a separate + function is that usually there are a lot of trace messages, so it might + make sense to separate them from other debug messages. + + In this version of wxLogTrace(), trace messages can be separated into + different categories and calls using this function only log the message if + the given @a mask is currently enabled in wxLog. This lets you selectively + trace only some operations and not others by enabling the desired trace + masks with wxLog::AddTraceMask() or by setting the + @ref overview_envvars "@c WXTRACE environment variable". + + The predefined string trace masks used by wxWidgets are: + + @beginDefList + @itemdef{ wxTRACE_MemAlloc, Trace memory allocation (new/delete) } + @itemdef{ wxTRACE_Messages, Trace window messages/X callbacks } + @itemdef{ wxTRACE_ResAlloc, Trace GDI resource allocation } + @itemdef{ wxTRACE_RefCount, Trace various ref counting operations } + @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) } + @endDefList + + @note Since both the mask and the format string are strings, this might + lead to function signature confusion in some cases: if you intend to + call the format string only version of wxLogTrace(), add a "%s" + format string parameter and then supply a second string parameter for + that "%s", the string mask version of wxLogTrace() will erroneously + get called instead, since you are supplying two string parameters to + the function. In this case you'll unfortunately have to avoid having + two leading string parameters, e.g. by adding a bogus integer (with + its "%d" format string). + + @header{wx/log.h} +*/ +void wxLogTrace(const char* mask, const char* formatString, ... ); void wxVLogTrace(const char* mask, - const char* formatString, - va_list argPtr); -void wxLogTrace(wxTraceMask mask, const char* formatString, - ... ); -void wxVLogTrace(wxTraceMask mask, const char* formatString, - va_list argPtr); + const char* formatString, + va_list argPtr); //@} +/** @ingroup group_funcmacro_log */ +//@{ +/** + Like wxLogDebug(), trace functions only do something in debug builds and + expand to nothing in the release one. The reason for making it a separate + function is that usually there are a lot of trace messages, so it might + make sense to separate them from other debug messages. + + This version of wxLogTrace() only logs the message if all the bits + corresponding to the @a mask are set in the wxLog trace mask which can be + set by calling wxLog::SetTraceMask(). This version is less flexible than + wxLogDebug(const char*,const char*,...) because it doesn't allow defining + the user trace masks easily. This is why it is deprecated in favour of + using string trace masks. + + The following bitmasks are defined for wxTraceMask: + + @beginDefList + @itemdef{ wxTraceMemAlloc, Trace memory allocation (new/delete) } + @itemdef{ wxTraceMessages, Trace window messages/X callbacks } + @itemdef{ wxTraceResAlloc, Trace GDI resource allocation } + @itemdef{ wxTraceRefCount, Trace various ref counting operations } + @itemdef{ wxTraceOleCalls, Trace OLE method calls (Win32 only) } + @endDefList + + @header{wx/log.h} +*/ +void wxLogTrace(wxTraceMask mask, const char* formatString, ... ); +void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr); +//@} +/** @ingroup group_funcmacro_log */ //@{ /** - The right functions for debug output. They only do something in debug - mode (when the preprocessor symbol __WXDEBUG__ is defined) and expand to + The right functions for debug output. They only do something in debug mode + (when the preprocessor symbol @c __WXDEBUG__ is defined) and expand to nothing in release mode (otherwise). + + @header{wx/log.h} */ void wxLogDebug(const char* formatString, ... ); void wxVLogDebug(const char* formatString, va_list argPtr); //@} - +/** @ingroup group_funcmacro_log */ //@{ /** - Messages logged by these functions will appear in the statusbar of the @a frame - or of the top level application window by default (i.e. when using + Messages logged by this function will appear in the statusbar of the + @a frame or of the top level application window by default (i.e. when using the second version of the functions). + If the target frame doesn't have a statusbar, the message will be lost. + + @header{wx/log.h} */ -void wxLogStatus(wxFrame* frame, const char* formatString, - ... ); -void wxVLogStatus(wxFrame* frame, const char* formatString, - va_list argPtr); +void wxLogStatus(wxFrame* frame, const char* formatString, ... ); +void wxVLogStatus(wxFrame* frame, const char* formatString, va_list argPtr); void wxLogStatus(const char* formatString, ... ); void wxVLogStatus(const char* formatString, va_list argPtr); //@} - +/** @ingroup group_funcmacro_log */ //@{ /** - Mostly used by wxWidgets itself, but might be handy for logging errors after - system call (API function) failure. It logs the specified message text as well - as the last system error code (@e errno or @e ::GetLastError() depending - on the platform) and the corresponding error message. The second form - of this function takes the error code explicitly as the first argument. + Mostly used by wxWidgets itself, but might be handy for logging errors + after system call (API function) failure. It logs the specified message + text as well as the last system error code (@e errno or @e ::GetLastError() + depending on the platform) and the corresponding error message. The second + form of this function takes the error code explicitly as the first + argument. @see wxSysErrorCode(), wxSysErrorMsg() + + @header{wx/log.h} */ void wxLogSysError(const char* formatString, ... ); -void wxVLogSysError(const char* formatString, - va_list argPtr); +void wxVLogSysError(const char* formatString, va_list argPtr); //@} - -/** - Returns the error code from the last system call. This function uses - @c errno on Unix platforms and @c GetLastError under Win32. - - @see wxSysErrorMsg(), wxLogSysError() -*/ -unsigned long wxSysErrorCode(); - - -/** - Returns the error message corresponding to the given system error code. If - @a errCode is 0 (default), the last error code (as returned by - wxSysErrorCode()) is used. - - @see wxSysErrorCode(), wxLogSysError() -*/ -const wxChar* wxSysErrorMsg(unsigned long errCode = 0); - - diff --git a/interface/memory.h b/interface/memory.h index d04ce2ae1d..0ffb85394a 100644 --- a/interface/memory.h +++ b/interface/memory.h @@ -238,31 +238,58 @@ public: // Global functions/macros // ============================================================================ +/** @ingroup group_funcmacro_log */ +//@{ + /** - @b NB: This function is now obsolete, replaced by @ref overview_logfunctions - "Log functions". - Calls wxTraceLevel with printf-style variable argument syntax. Output - is directed to the current output stream (see wxDebugContext). - The first argument should be the level at which this information is appropriate. - It will only be output if the level returned by wxDebugContext::GetLevel is - equal to or greater than - this value. + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Calls wxTrace() with printf-style variable argument syntax. Output is + directed to the current output stream (see wxDebugContext). + + @header{wx/memory.h} */ -#define WXTRACELEVEL() /* implementation is private */ +#define WXTRACE(format, ...) /** - @b NB: This function is now obsolete, replaced by @ref overview_logfunctions - "Log functions". - Takes printf-style variable argument syntax. Output - is directed to the current output stream (see wxDebugContext). + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Calls wxTraceLevel with printf-style variable argument syntax. Output is + directed to the current output stream (see wxDebugContext). The first + argument should be the level at which this information is appropriate. It + will only be output if the level returned by wxDebugContext::GetLevel is + equal to or greater than this value. + + @header{wx/memory.h} */ -void wxTrace(const wxString& fmt, ... ); +#define WXTRACELEVEL(level, format, ...) /** - @b NB: This macro is now obsolete, replaced by @ref overview_logfunctions "Log - functions". - Calls wxTrace with printf-style variable argument syntax. Output - is directed to the current output stream (see wxDebugContext). + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Takes printf-style variable argument syntax. Output is directed to the + current output stream (see wxDebugContext). + + @header{wx/memory.h} */ -#define Include files WXTRACE() /* implementation is private */ +void wxTrace(const wxString& format, ...); + +/** + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Takes @e printf() style variable argument syntax. Output is directed to the + current output stream (see wxDebugContext). The first argument should be + the level at which this information is appropriate. It will only be output + if the level returned by wxDebugContext::GetLevel() is equal to or greater + than this value. + + @header{wx/memory.h} +*/ +void wxTraceLevel(int level, const wxString& format, ...); + +//@} diff --git a/interface/utils.h b/interface/utils.h index 0d6d74a2b7..ca40c98c0e 100644 --- a/interface/utils.h +++ b/interface/utils.h @@ -206,6 +206,61 @@ bool wxUnsetEnv(const wxString& var); +/** @ingroup group_funcmacro_log */ +//@{ + +/** + @deprecated Replaced by wxLogDebug(). + + Displays a debugging message. Under Windows, this will appear on the + debugger command window, and under Unix, it will be written to standard + error. + + The syntax is identical to @e printf(), pass a format string and a variable + list of arguments. + + @note Under Windows, if your application crashes before the message appears + in the debugging window, put a wxYield() call after each wxDebugMsg() + call. wxDebugMsg() seems to be broken under WIN32s (at least for + Watcom C++): preformat your messages and use OutputDebugString + instead. + + @header{wx/utils.h} +*/ +void wxDebugMsg(const wxString& format, ... ); + +/** + @deprecated Replaced by wxLogFatalError(). + + Displays @a message and exits. This writes to standard error under Unix, + and pops up a message box under Windows. Used for fatal internal wxWidgets + errors. + + @eee wxError() + + @header{wx/utils.h} +*/ +void wxFatalError(const wxString& message, + const wxString& title = "wxWidgets Fatal Error"); + +/** + @deprecated Replaced by wxLogError(). + + Displays @a message and continues. This writes to standard error under + Unix, and pops up a message box under Windows. Used for internal wxWidgets + errors. + + @see wxFatalError() + + @header{wx/utils.h} +*/ +void wxError(const wxString& message, + const wxString& title = "wxWidgets Internal Error"); + +//@} + + + /** Returns the type of power source as one of @c wxPOWER_SOCKET, @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @@ -236,18 +291,6 @@ wxString wxGetUserId(); bool wxGetUserId(char* buf, int sz); //@} -/** - @b NB: This function is now obsolete, please use - wxLogFatalError() instead. - Displays @a msg and exits. This writes to standard error under Unix, - and pops up a message box under Windows. Used for fatal internal - wxWidgets errors. See also wxError(). - - @header{wx/utils.h} -*/ -void wxFatalError(const wxString& msg, - const wxString& title = "wxWidgets Fatal Error"); - /** Returns battery state as one of @c wxBATTERY_NORMAL_STATE, @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, @@ -295,24 +338,6 @@ long wxNewId(); */ void wxRegisterId(long id); -/** - @b NB: This function is now obsolete, replaced by Log - functions() and wxLogDebug() in particular. - Display a debugging message; under Windows, this will appear on the - debugger command window, and under Unix, it will be written to standard - error. - The syntax is identical to @b printf: pass a format string and a - variable list of arguments. - @b Tip: under Windows, if your application crashes before the - message appears in the debugging window, put a wxYield call after - each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s - (at least for Watcom C++): preformat your messages and use OutputDebugString - instead. - - @header{wx/utils.h} -*/ -void wxDebugMsg(const wxString& fmt, ... ); - /** For normal keys, returns @true if the specified key is currently down. For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @@ -398,18 +423,6 @@ void wxEnableTopLevelWindows(bool enable = true); wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All); -/** - @b NB: This function is now obsolete, please use wxLogError() - instead. - Displays @a msg and continues. This writes to standard error under - Unix, and pops up a message box under Windows. Used for internal - wxWidgets errors. See also wxFatalError(). - - @header{wx/utils.h} -*/ -void wxError(const wxString& msg, - const wxString& title = "wxWidgets Internal Error"); - /** Open the @a url in user's default browser. If @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL