Use /bin/echo for creation of Mac OS X PkgInfo files.

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

diff --git a/interface/wx/debug.h b/interface/wx/debug.h
index 5c446af318dbb5da499e7ddbdee7387c5989fdcf..2c03d20a45afd628c5edd5ad9a920bfadfeea63d 100644 (file)
--- a/interface/wx/debug.h
+++ b/interface/wx/debug.h
@@ -1,28 +1,59 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        debug.h
+// Name:        wx/debug.h
 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /** @addtogroup group_funcmacro_debug */
 //@{
 
+/**
+    Exits the program immediately.
+
+    This is a simple wrapper for the standard abort() function which is not
+    available under all platforms (currently only Windows CE doesn't provide
+    it).
+
+    @since 2.9.4
+ */
+void wxAbort();
+
 /**
     @def wxDEBUG_LEVEL
 
     Preprocessor symbol defining the level of debug support available.
 
-    Currently wxDEBUG_LEVEL is 0 in release builds (__WXDEBUG__ not defined)
-    and 1 in debug builds (it is). In the immediate future this will change
-    however and this symbol will be defined directly as 0, 1 or 2 while
-    __WXDEBUG__ won't be used by wxWidgets any longer.
+    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.
 
@@ -218,9 +249,33 @@ typedef void (*wxAssertHandler_t)(const wxString& file,
     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
+    wxIMPLEMENT_APP().
+
+    By default, assert message boxes are suppressed in release build by
+    wxIMPLEMENT_APP() which uses this macro. If you don't use wxIMPLEMENT_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
@@ -245,7 +300,7 @@ void wxDisableAsserts();
     Will always generate an assert error with specified message if this code is
     reached (in debug mode).
 
-    This macro is useful for marking unreachable" code areas, for example it
+    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.
 
@@ -298,15 +353,34 @@ bool wxIsDebuggerRunning();
         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);
 
 /**
-    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.
+    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.
+
+    @since 2.9.1
+
+    @header{wx/debug.h}
+ */
+void wxSetDefaultAssertHandler();
+
+/**
+    Generate 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.
+
+    If @c wxDEBUG_LEVEL is 0 (which is not the default) this function does
+    nothing.
 
     @header{wx/debug.h}
 */