X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..de022e4f1197d146e9bdd6aeb2ac0ee9cb217737:/interface/debug.h diff --git a/interface/debug.h b/interface/debug.h index 4420ad5db2..6338b91479 100644 --- a/interface/debug.h +++ b/interface/debug.h @@ -1,164 +1,220 @@ ///////////////////////////////////////////////////////////////////////////// // Name: debug.h -// Purpose: documentation for global functions +// Purpose: interface of global functions // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** @ingroup group_funcmacro_debug */ +//@{ + /** -Will always generate an assert error if this code is reached (in debug mode). + Assert macro. An error message will be generated if the condition is @false in + debug mode, but nothing will be done in the release build. + Please note that the condition in wxASSERT() should have no side effects + because it will not be executed in release mode at all. -See also: wxFAIL_MSG + @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT() + + @header{wx/debug.h} */ -#define wxFAIL() /* implementation is private */ +#define wxASSERT( condition ) + +/** + This macro results in a + @ref overview_wxcompiletimeassert "compile time assertion failure" if the + size of the given @c type is less than @c size bits. + You may use it like this, for example: + + @code + // we rely on the int being able to hold values up to 2^32 + wxASSERT_MIN_BITSIZE(int, 32); + + // can't work with the platforms using UTF-8 for wchar_t + wxASSERT_MIN_BITSIZE(wchar_t, 16); + @endcode + + @header{wx/debug.h} +*/ +#define wxASSERT_MIN_BITSIZE( type, size ) /** -This function is called whenever one of debugging macros fails (i.e. condition -is @false in an assertion). It is only defined in the debug mode, in release -builds the wxCHECK failures don't result in anything. + Assert macro with message. An error message will be generated if the + condition is @false. -To override the default behaviour in the debug builds which is to show the user -a dialog asking whether he wants to abort the program, continue or continue -ignoring any subsequent assert failures, you may override -wxApp::OnAssertFailure which is called by this function if -the global application object exists. + @see wxASSERT(), wxCOMPILE_TIME_ASSERT() + + @header{wx/debug.h} */ -void wxOnAssert(const char * fileName, int lineNumber, - const char * func, - const char * cond, - const char * msg = @NULL); +#define wxASSERT_MSG( condition, message ) /** - In debug mode (when @c __WXDEBUG__ is defined) this function generates a - debugger exception meaning that the control is passed to the debugger if one is - attached to the process. Otherwise the program just terminates abnormally. + Checks that the condition is @true, returns with the given return value if + not (stops execution in debug mode). This check is done even in release + mode. - In release mode this function does nothing. + @header{wx/debug.h} */ -void wxTrap(); +#define wxCHECK( condition, retValue ) /** - Will always generate an assert error with specified message if this code is - reached (in debug mode). + Checks that the condition is @true, returns with the given return value if + not (stops execution in debug mode). This check is done even in release + mode. - This macro is useful for marking unreachable" code areas, for example - it may be used in the "default:" branch of a switch statement if all possible - cases are processed above. + This macro may be only used in non-void functions, see also wxCHECK_RET(). - @sa wxFAIL + @header{wx/debug.h} */ -#define wxFAIL_MSG(msg) /* implementation is private */ +#define wxCHECK_MSG( condition, retValue, message ) /** - Checks that the condition is @true, returns with the given return value if not - (FAILs in debug mode). - This check is done even in release mode. + Checks that the condition is @true, and returns if not (stops execution + with the given error message in debug mode). This check is done even in + release mode. + + This macro should be used in void functions instead of wxCHECK_MSG(). + + @header{wx/debug.h} */ -#define wxCHECK(condition, retValue) /* implementation is private */ +#define wxCHECK_RET( condition, message ) /** - This macro results in a - @ref overview_wxcompiletimeassert "compile time assertion failure" if the size - of the given type @e type is less than @e size bits. + Checks that the condition is @true, and if not, it will wxFAIL() and + execute the given @c operation if it is not. This is a generalisation of + wxCHECK() and may be used when something else than just returning from the + function must be done when the @c condition is @false. This check is done + even in release mode. - You may use it like this, for example: - @code - // we rely on the int being able to hold values up to 2^32 - wxASSERT_MIN_BITSIZE(int, 32); + @header{wx/debug.h} +*/ +#define wxCHECK2(condition, operation) - // can't work with the platforms using UTF-8 for wchar_t - wxASSERT_MIN_BITSIZE(wchar_t, 16); - @endcode +/** + This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified + @c message is called instead of wxFAIL() if the @c condition is @false. + + @header{wx/debug.h} */ -#define wxASSERT_MIN_BITSIZE(type, size) /* implementation is private */ +#define wxCHECK2_MSG( condition, operation, message ) /** - Assert macro with message. An error message will be generated if the condition - is @false. + Using wxCOMPILE_TIME_ASSERT() results in a compilation error if the + specified @c condition is @false. The compiler error message should include + the @c message identifier - please note that it must be a valid C++ + identifier and not a string unlike in the other cases. - @sa wxASSERT, wxCOMPILE_TIME_ASSERT + This macro is mostly useful for testing the expressions involving the + @c sizeof operator as they can't be tested by the preprocessor but it is + sometimes desirable to test them at the compile time. + + Note that this macro internally declares a struct whose name it tries to + make unique by using the @c __LINE__ in it but it may still not work if you + use it on the same line in two different source files. In this case you may + either change the line in which either of them appears on or use the + wxCOMPILE_TIME_ASSERT2() macro. + + Also note that Microsoft Visual C++ has a bug which results in compiler + errors if you use this macro with 'Program Database For Edit And Continue' + (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok + though) for the code making use of this macro. + + @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE() + + @header{wx/debug.h} */ -#define wxASSERT_MSG(condition, msg) /* implementation is private */ +#define wxCOMPILE_TIME_ASSERT( condition, message ) /** - This is the same as wxCHECK2, but - wxFAIL_MSG with the specified @e msg is called - instead of wxFAIL() if the @e condition is @false. + This macro is identical to wxCOMPILE_TIME_ASSERT() except that it allows + you to specify a unique @c name for the struct internally defined by this + macro to avoid getting the compilation errors described for + wxCOMPILE_TIME_ASSERT(). + + @header{wx/debug.h} */ -#define wxCHECK2(condition, operation, msg) /* implementation is private */ +#define wxCOMPILE_TIME_ASSERT2(condition, message, name) /** - Assert macro. An error message will be generated if the condition is @false in - debug mode, but nothing will be done in the release build. + Will always generate an assert error if this code is reached (in debug + mode). - Please note that the condition in wxASSERT() should have no side effects - because it will not be executed in release mode at all. + @see wxFAIL_MSG() - @sa wxASSERT_MSG, wxCOMPILE_TIME_ASSERT + @header{wx/debug.h} */ -#define wxASSERT(condition) /* implementation is private */ +#define wxFAIL() /** - Checks that the condition is @true, and returns if not (FAILs with given error - message in debug mode). This check is done even in release mode. + Will always generate an assert error with specified message if this code is + reached (in debug mode). - This macro should be used in void functions instead of - wxCHECK_MSG. + This macro is useful for marking unreachable" code areas, for example it + may be used in the "default:" branch of a switch statement if all possible + cases are processed above. + + @see wxFAIL() + + @header{wx/debug.h} */ -#define wxCHECK_RET(condition, msg) /* implementation is private */ +#define wxFAIL_MSG( message ) /** - Checks that the condition is @true and wxFAIL and execute - @e operation if it is not. This is a generalisation of - wxCHECK and may be used when something else than just - returning from the function must be done when the @e condition is @false. + Returns @true if the program is running under debugger, @false otherwise. - This check is done even in release mode. + Please note that this function is currently only implemented for Win32 and + Mac builds using CodeWarrior and always returns @false elsewhere. + + @header{wx/debug.h} */ -#define wxCHECK2(condition, operation) /* implementation is private */ +bool wxIsDebuggerRunning(); /** - This macro is identical to wxCOMPILE_TIME_ASSERT2 - except that it allows you to specify a unique @e name for the struct - internally defined by this macro to avoid getting the compilation errors - described above. + This function is called whenever one of debugging macros fails (i.e. + condition is @false in an assertion). It is only defined in the debug mode, + in release builds the wxCHECK() failures don't result in anything. + + To override the default behaviour in the debug builds which is to show the + user a dialog asking whether he wants to abort the program, continue or + continue ignoring any subsequent assert failures, you may override + wxApp::OnAssertFailure() which is called by this function if the global + application object exists. + + @header{wx/debug.h} */ -#define wxCOMPILE_TIME_ASSERT(condition, msg, name) /* implementation is private */ +void wxOnAssert( const char* fileName, + int lineNumber, + const char* function, + const char* condition, + const char* message = NULL ); /** - Checks that the condition is @true, returns with the given return value if not - (FAILs in debug mode). - This check is done even in release mode. + In debug mode (when @c __WXDEBUG__ is defined) this function generates a + debugger exception meaning that the control is passed to the debugger if + one is attached to the process. Otherwise the program just terminates + abnormally. In release mode this function does nothing. - This macro may be only used in non-void functions, see also - wxCHECK_RET. + @header{wx/debug.h} */ -#define wxCHECK_MSG(condition, retValue, msg) /* implementation is private */ +void wxTrap(); -/** - Using @c wxCOMPILE_TIME_ASSERT results in a compilation error if the - specified @e condition is @false. The compiler error message should include - the @e msg identifier - please note that it must be a valid C++ identifier - and not a string unlike in the other cases. +//@} - This macro is mostly useful for testing the expressions involving the - @c sizeof operator as they can't be tested by the preprocessor but it is - sometimes desirable to test them at the compile time. - Note that this macro internally declares a struct whose name it tries to make - unique by using the @c __LINE__ in it but it may still not work if you - use it on the same line in two different source files. In this case you may - either change the line in which either of them appears on or use the - wxCOMPILE_TIME_ASSERT2 macro. - Also note that Microsoft Visual C++ has a bug which results in compiler errors - if you use this macro with 'Program Database For Edit And Continue' - (@c /ZI) option, so you shouldn't use it ('Program Database' - (@c /Zi) is ok though) for the code making use of this macro. +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + This macro expands to the name of the current function if the compiler + supports any of @c __FUNCTION__, @c __func__ or equivalent variables or + macros or to @NULL if none of them is available. - @sa wxASSERT_MSG, wxASSERT_MIN_BITSIZE + @header{wx/debug.h} */ -#define wxCOMPILE_TIME_ASSERT(condition, msg) /* implementation is private */ +#define __WXFUNCTION__ + +//@}