Document "raw control" use with accelerators.

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

diff --git a/interface/wx/debug.h b/interface/wx/debug.h
index d0e98d385e83c1e89b135556b8a56cd5398af788..7e787e88c4d7d525d1eb1f1a1026ae19b685209e 100644 (file)
--- a/interface/wx/debug.h
+++ b/interface/wx/debug.h
@@ -1,14 +1,70 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

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

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-/** @ingroup 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.
+
+    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 +81,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 +245,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
+    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


@@ -187,7 +300,7 @@
     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.
 


@@ -204,56 +317,74 @@
     Returns @true if the program is running under debugger, @false otherwise.
 
     Please note that this function is currently only implemented for Win32 and
     Returns @true if the program is running under debugger, @false otherwise.
 
     Please note that this function is currently only implemented for Win32 and

-    Mac builds using CodeWarrior and always returns @false elsewhere.
+    always returns @false elsewhere.

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

 
 

-    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.
+    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.

 
 

-    @header{wx/debug.h}
-*/
-void wxOnAssert( const char* fileName,
-                  int lineNumber,
-                  const char* function,
-                  const char* condition,
-                  const char* message = NULL );
+    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.

 
 

-/**
-    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 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}
 
     @header{wx/debug.h}

-*/
-void wxTrap();
+ */
+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.

 
 

+    @since 2.9.1

 
 

-/** @ingroup group_funcmacro_misc */
-//@{
+    @header{wx/debug.h}
+ */
+void wxSetDefaultAssertHandler();

 
 /**
 
 /**

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

-#define __WXFUNCTION__
+void wxTrap();

 
 //@}
 
 
 //@}