]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/debug.h
make wxRearrangeDialog more customizable and add an example of customizing it to...
[wxWidgets.git] / interface / wx / debug.h
... / ...
CommitLineData
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*/
211bool 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*/
226void 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*/
240void 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