interface/debug.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        debug.h
   3 // Purpose:     interface of global functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /** @ingroup group_funcmacro_debug */
  10 //@{
  11
  12 /**
  13     Assert macro. An error message will be generated if the condition is @false in
  14     debug mode, but nothing will be done in the release build.
  15     Please note that the condition in wxASSERT() should have no side effects
  16     because it will not be executed in release mode at all.
  17
  18     @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
  19
  20     @header{wx/debug.h}
  21 */
  22 #define wxASSERT( condition )
  23
  24 /**
  25     This macro results in a
  26     @ref overview_wxcompiletimeassert "compile time assertion failure" if the
  27     size of the given @c type is less than @c size bits.
  28
  29     You may use it like this, for example:
  30
  31     @code
  32     // we rely on the int being able to hold values up to 2^32
  33     wxASSERT_MIN_BITSIZE(int, 32);
  34
  35     // can't work with the platforms using UTF-8 for wchar_t
  36     wxASSERT_MIN_BITSIZE(wchar_t, 16);
  37     @endcode
  38
  39     @header{wx/debug.h}
  40 */
  41 #define wxASSERT_MIN_BITSIZE( type, size )
  42
  43 /**
  44     Assert macro with message. An error message will be generated if the
  45     condition is @false.
  46
  47     @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
  48
  49     @header{wx/debug.h}
  50 */
  51 #define wxASSERT_MSG( condition, message )
  52
  53 /**
  54     Checks that the condition is @true, returns with the given return value if
  55     not (stops execution in debug mode). This check is done even in release
  56     mode.
  57
  58     @header{wx/debug.h}
  59 */
  60 #define wxCHECK( condition, retValue )
  61
  62 /**
  63     Checks that the condition is @true, returns with the given return value if
  64     not (stops execution in debug mode). This check is done even in release
  65     mode.
  66
  67     This macro may be only used in non-void functions, see also wxCHECK_RET().
  68
  69     @header{wx/debug.h}
  70 */
  71 #define wxCHECK_MSG( condition, retValue, message )
  72
  73 /**
  74     Checks that the condition is @true, and returns if not (stops execution
  75     with the given error message in debug mode). This check is done even in
  76     release mode.
  77
  78     This macro should be used in void functions instead of wxCHECK_MSG().
  79
  80     @header{wx/debug.h}
  81 */
  82 #define wxCHECK_RET( condition, message )
  83
  84 /**
  85     Checks that the condition is @true, and if not, it will wxFAIL() and
  86     execute the given @c operation if it is not. This is a generalisation of
  87     wxCHECK() and may be used when something else than just returning from the
  88     function must be done when the @c condition is @false. This check is done
  89     even in release mode.
  90
  91     @header{wx/debug.h}
  92 */
  93 #define wxCHECK2(condition, operation)
  94
  95 /**
  96     This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified
  97     @c message is called instead of wxFAIL() if the @c condition is @false.
  98
  99     @header{wx/debug.h}
 100 */
 101 #define wxCHECK2_MSG( condition, operation, message )
 102
 103 /**
 104     Using wxCOMPILE_TIME_ASSERT() results in a compilation error if the
 105     specified @c condition is @false. The compiler error message should include
 106     the @c message identifier - please note that it must be a valid C++
 107     identifier and not a string unlike in the other cases.
 108
 109     This macro is mostly useful for testing the expressions involving the
 110     @c sizeof operator as they can't be tested by the preprocessor but it is
 111     sometimes desirable to test them at the compile time.
 112
 113     Note that this macro internally declares a struct whose name it tries to
 114     make unique by using the @c __LINE__ in it but it may still not work if you
 115     use it on the same line in two different source files. In this case you may
 116     either change the line in which either of them appears on or use the
 117     wxCOMPILE_TIME_ASSERT2() macro.
 118
 119     Also note that Microsoft Visual C++ has a bug which results in compiler
 120     errors if you use this macro with 'Program Database For Edit And Continue'
 121     (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok
 122     though) for the code making use of this macro.
 123
 124     @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
 125
 126     @header{wx/debug.h}
 127 */
 128 #define wxCOMPILE_TIME_ASSERT( condition, message )
 129
 130 /**
 131     This macro is identical to wxCOMPILE_TIME_ASSERT() except that it allows
 132     you to specify a unique @c name for the struct internally defined by this
 133     macro to avoid getting the compilation errors described for
 134     wxCOMPILE_TIME_ASSERT().
 135
 136     @header{wx/debug.h}
 137 */
 138 #define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 139
 140 /**
 141     Will always generate an assert error if this code is reached (in debug
 142     mode).
 143
 144     @see wxFAIL_MSG()
 145
 146     @header{wx/debug.h}
 147 */
 148 #define wxFAIL()
 149
 150 /**
 151     Will always generate an assert error with specified message if this code is
 152     reached (in debug mode).
 153
 154     This macro is useful for marking unreachable" code areas, for example it
 155     may be used in the "default:" branch of a switch statement if all possible
 156     cases are processed above.
 157
 158     @see wxFAIL()
 159
 160     @header{wx/debug.h}
 161 */
 162 #define wxFAIL_MSG( message )
 163
 164 /**
 165     Returns @true if the program is running under debugger, @false otherwise.
 166
 167     Please note that this function is currently only implemented for Win32 and
 168     Mac builds using CodeWarrior and always returns @false elsewhere.
 169
 170     @header{wx/debug.h}
 171 */
 172 bool wxIsDebuggerRunning();
 173
 174 /**
 175     This function is called whenever one of debugging macros fails (i.e.
 176     condition is @false in an assertion). It is only defined in the debug mode,
 177     in release builds the wxCHECK() failures don't result in anything.
 178
 179     To override the default behaviour in the debug builds which is to show the
 180     user a dialog asking whether he wants to abort the program, continue or
 181     continue ignoring any subsequent assert failures, you may override
 182     wxApp::OnAssertFailure() which is called by this function if the global
 183     application object exists.
 184
 185     @header{wx/debug.h}
 186 */
 187 void wxOnAssert( const char* fileName,
 188                   int lineNumber,
 189                   const char* function,
 190                   const char* condition,
 191                   const char* message = NULL );
 192
 193 /**
 194     In debug mode (when @c __WXDEBUG__ is defined) this function generates a
 195     debugger exception meaning that the control is passed to the debugger if
 196     one is attached to the process. Otherwise the program just terminates
 197     abnormally. In release mode this function does nothing.
 198
 199     @header{wx/debug.h}
 200 */
 201 void wxTrap();
 202
 203 //@}
 204
 205
 206
 207 /** @ingroup group_funcmacro_misc */
 208 //@{
 209
 210 /**
 211     This macro expands to the name of the current function if the compiler
 212     supports any of @c __FUNCTION__, @c __func__ or equivalent variables or
 213     macros or to @NULL if none of them is available.
 214
 215     @header{wx/debug.h}
 216 */
 217 #define __WXFUNCTION__
 218
 219 //@}
 220