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$
 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /** @addtogroup group_funcmacro_debug */
 //@{
 
 /////////////////////////////////////////////////////////////////////////////
 
 /** @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.
 
 /**
     @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
 
 
     @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.
 
 /**
     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.
     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();
 
  */
 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
 /**
     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).
 
     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.
 
     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.
 
         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);
 
 /**
     @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}
 */
 
     @header{wx/debug.h}
 */