Minor clarifation and typo fix

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

diff --git a/interface/wx/debug.h b/interface/wx/debug.h
index 1a6e697d97a4c4155e76f240261a8599a2a9d94b..ac3164e262c9266ba9163e6342d6d08734103f7d 100644 (file)
--- a/interface/wx/debug.h
+++ b/interface/wx/debug.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        debug.h
+// Name:        wx/debug.h

 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -9,6 +9,51 @@
 /** @addtogroup group_funcmacro_debug */
 //@{
 
 /** @addtogroup group_funcmacro_debug */
 //@{
 

+/**
+    @def wxDEBUG_LEVEL
+
+    Preprocessor symbol defining the level of debug support available.
+
+    This symbol is defined to 1 by default meaning that asserts are compiled in
+    (although they may be disabled by a call to wxDisableAsserts()). You may
+    predefine it as 0 prior to including any wxWidgets headers to omit the
+    calls to wxASSERT() and related macros entirely in your own code and you
+    may also predefine it as 0 when building wxWidgets to also avoid including
+    any asserts in wxWidgets itself.
+
+    Alternatively, you may predefine it as 2 to include wxASSERT_LEVEL_2() and
+    similar macros which are used for asserts which have non-trivial run-time
+    costs and so are disabled by default.
+
+    @since 2.9.1
+
+    @header{wx/debug.h}
+ */
+#define wxDEBUG_LEVEL
+
+/**
+    @def __WXDEBUG__
+
+    Compatibility macro indicating presence of debug support.
+
+    This symbol is defined if wxDEBUG_LEVEL is greater than 0 and undefined
+    otherwise.
+
+    @header{wx/debug.h}
+ */
+#define __WXDEBUG__
+
+/**
+    Type for the function called in case of assert failure.
+
+    @see wxSetAssertHandler()
+ */
+typedef void (*wxAssertHandler_t)(const wxString& file,
+                                  int line,
+                                  const wxString& func,
+                                  const wxString& cond,
+                                  const wxString& msg);
+

 /**
     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.
 /**
     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.


@@ -25,6 +70,32 @@
 */
 #define wxASSERT( condition )
 
 */
 #define wxASSERT( condition )
 

+/**
+    Assert macro for expensive run-time checks.
+
+    This macro does nothing unless wxDEBUG_LEVEL is 2 or more and is meant to
+    be used for the assertions with noticeable performance impact and which,
+    hence, should be disabled during run-time.
+
+    If wxDEBUG_LEVEL is 2 or more, it becomes the same as wxASSERT().
+
+    @header{wx/debug.h}
+ */
+#define wxASSERT_LEVEL_2( condition )
+
+/**
+    Assert macro with a custom message for expensive run-time checks.
+
+    If wxDEBUG_LEVEL is 2 or more, this is the same as wxASSERT_MSG(),
+    otherwise it doesn't do anything at all.
+
+    @see wxASSERT_LEVEL_2()
+
+    @header{wx/debug.h}
+ */
+#define wxASSERT_LEVEL_2_MSG( condition, msg)
+
+

 /**
     This macro results in a @ref wxCOMPILE_TIME_ASSERT "compile time assertion failure"
     if the size of the given @c type is less than @c size bits.
 /**
     This macro results in a @ref wxCOMPILE_TIME_ASSERT "compile time assertion failure"
     if the size of the given @c type is less than @c size bits.


@@ -163,6 +234,37 @@
 */
 #define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 
 */
 #define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 

+/**
+    Disable the condition checks in the assertions.
+
+    This is the same as calling wxSetAssertHandler() with @NULL handler.
+
+    @since 2.9.0
+
+    @header{wx/debug.h}
+ */
+void wxDisableAsserts();
+
+/**
+    @def wxDISABLE_ASSERTS_IN_RELEASE_BUILD
+
+    Use this macro to disable asserts in release build when not using
+    IMPLEMENT_APP().
+
+    By default, assert message boxes are suppressed in release build by
+    IMPLEMENT_APP() which uses this macro. If you don't use IMPLEMENT_APP()
+    because your application initializes wxWidgets directly (e.g. calls
+    wxEntry() or wxEntryStart() itself) but still want to suppress assert
+    notifications in release build you need to use this macro directly.
+
+    @see wxDISABLE_DEBUG_SUPPORT()
+
+    @since 2.9.1
+
+    @header{wx/debug.h}
+ */
+#define wxDISABLE_ASSERTS_IN_RELEASE_BUILD() wxDisableAsserts()
+

 /**
     Will always generate an assert error if this code is reached (in debug mode).
     Note that you don't have to (and cannot) use brackets when invoking this
 /**
     Will always generate an assert error if this code is reached (in debug mode).
     Note that you don't have to (and cannot) use brackets when invoking this


@@ -211,23 +313,54 @@
 bool wxIsDebuggerRunning();
 
 /**
 bool wxIsDebuggerRunning();
 
 /**

-    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.
+    Sets the function to be called in case of assertion failure.
+
+    The default assert handler forwards to wxApp::OnAssertFailure() whose
+    default behaviour is, in turn, to show the standard assertion failure
+    dialog if a wxApp object exists or shows the same dialog itself directly
+    otherwise.
+
+    While usually it is enough -- and more convenient -- to just override
+    OnAssertFailure(), to handle all assertion failures, including those
+    occurring even before wxApp object creation of after its destruction you
+    need to provide your assertion handler function.
+
+    This function also provides a simple way to disable all asserts: simply
+    pass @NULL pointer to it. Doing this will result in not even evaluating
+    assert conditions at all, avoiding almost all run-time cost of asserts.
+
+    Notice that this function is not MT-safe, so you should call it before
+    starting any other threads.
+
+    The return value of this function is the previous assertion handler. It can
+    be called after any pre-processing by your handler and can also be restored
+    later if you uninstall your handler.
+
+    @param handler
+        The function to call in case of assertion failure or @NULL.
+    @return
+        The previous assert handler which is not @NULL by default but could be
+        @NULL if it had been previously set to this value using this function.
+
+    @since 2.9.0
+
+    @header{wx/debug.h}
+ */
+wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler);
+
+/**
+    Reset the assert handler to default function which shows a message box when
+    an assert happens.
+
+    This can be useful for the applications compiled in release build (with @c
+    NDEBUG defined) for which the asserts are by default disabled: if you wish
+    to enable them even in this case you need to call this function.

 
 

-    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.
+    @since 2.9.1

 
     @header{wx/debug.h}
 
     @header{wx/debug.h}

-*/
-void wxOnAssert( const char* fileName,
-                  int lineNumber,
-                  const char* function,
-                  const char* condition,
-                  const char* message = NULL );
+ */
+void wxSetDefaultAssertHandler();

 
 /**
     In debug mode (when @c __WXDEBUG__ is defined) this function generates a
 
 /**
     In debug mode (when @c __WXDEBUG__ is defined) this function generates a