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