/////////////////////////////////////////////////////////////////////////////
// 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__
+
+//@}
projects / wxWidgets.git / blobdiff