1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDebugContext
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
13 A class for performing various debugging and memory tracing operations.
15 Full functionality (such as printing out objects currently allocated) is
16 only present in a debugging build of wxWidgets, i.e. if the __WXDEBUG__
17 symbol is defined. wxDebugContext and related functions and macros can be
18 compiled out by setting wxUSE_DEBUG_CONTEXT to 0 is setup.h
23 @see @ref overview_debugging
29 Checks the memory blocks for errors, starting from the currently set
32 @return Returns the number of errors, so a value of zero represents
33 success. Returns -1 if an error was detected that prevents
36 static int Check(bool checkAll
= false);
39 Performs a memory dump from the currently set checkpoint, writing to the
40 current debug stream. Calls the @b Dump member function for each wxObject
43 @return @true if the function succeeded, @false otherwise.
48 Returns @true if the memory allocator checks all previous memory blocks for
51 By default, this is @false since it slows down execution considerably.
53 @see SetCheckPrevious()
55 static bool GetCheckPrevious();
58 Returns @true if debug mode is on.
60 If debug mode is on, the wxObject new and delete operators store or use
61 information about memory allocation. Otherwise, a straight malloc and
62 free will be performed by these operators.
66 static bool GetDebugMode();
69 Gets the debug level (default 1).
71 The debug level is used by the wxTraceLevel function and the WXTRACELEVEL
72 macro to specify how detailed the trace information is; setting a
73 different level will only have an effect if trace statements in the
74 application specify a value other than one.
77 This is obsolete, replaced by wxLog functionality.
81 static int GetLevel();
84 Returns the output stream associated with the debug context.
87 This is obsolete, replaced by wxLog functionality.
94 Returns a pointer to the output stream buffer associated with the debug context.
95 There may not necessarily be a stream buffer if the stream has been set
99 This is obsolete, replaced by wxLog functionality.
101 streambuf
* GetStreamBuf();
104 Returns @true if there is a stream currently associated
105 with the debug context.
108 This is obsolete, replaced by wxLog functionality.
110 @see SetStream(), GetStream()
115 Prints a list of the classes declared in this application, giving derivation
116 and whether instances of this class can be dynamically created.
118 @see PrintStatistics()
120 static bool PrintClasses();
123 Performs a statistics analysis from the currently set checkpoint, writing
124 to the current debug stream. The number of object and non-object
125 allocations is printed, together with the total size.
128 If @true, the function will also print how many objects of each class
129 have been allocated, and the space taken by these class instances.
131 @see PrintStatistics()
133 static bool PrintStatistics(bool detailed
= true);
136 Tells the memory allocator to check all previous memory blocks for errors.
137 By default, this is @false since it slows down execution considerably.
139 @see GetCheckPrevious()
141 static void SetCheckPrevious(bool check
);
144 Sets the current checkpoint: Dump and PrintStatistics operations will
145 be performed from this point on. This allows you to ignore allocations
146 that have been performed up to this point.
149 If @true, the checkpoint is reset to include all memory allocations
150 since the program started.
152 static void SetCheckpoint(bool all
= false);
155 Sets the debug mode on or off.
157 If debug mode is on, the wxObject new and delete operators store or use
158 information about memory allocation. Otherwise, a straight malloc and free
159 will be performed by these operators.
161 By default, debug mode is on if __WXDEBUG__ is defined. If the application
162 uses this function, it should make sure that all object memory allocated
163 is deallocated with the same value of debug mode. Otherwise, the delete
164 operator might try to look for memory information that does not exist.
168 static void SetDebugMode(bool debug
);
171 Sets the current debug file and creates a stream.
172 This will delete any existing stream and stream buffer.
174 By default, the debug context stream outputs to the debugger (Windows)
175 or standard error (other platforms).
177 bool SetFile(const wxString
& filename
);
180 Sets the debug level (default 1).
182 The debug level is used by the wxTraceLevel function and the WXTRACELEVEL
183 macro to specify how detailed the trace information is; setting
184 a different level will only have an effect if trace statements in the
185 application specify a value other than one.
188 This is obsolete, replaced by wxLog functionality.
192 static void SetLevel(int level
);
195 Installs a function to be called at the end of wxWidgets shutdown.
196 It will be called after all files with global instances of
197 wxDebugContextDumpDelayCounter have run their destructors.
199 The shutdown function must be take no parameters and return nothing.
201 static void SetShutdownNotifyFunction(wxShutdownNotifyFunction func
);
204 Sets the debugging stream to be the debugger (Windows) or standard error (other
207 This is the default setting. The existing stream will be flushed and deleted.
210 This is obsolete, replaced by wxLog functionality.
212 bool SetStandardError();
215 Sets the stream and optionally, stream buffer associated with the debug context.
216 This operation flushes and deletes the existing stream (and stream buffer if any).
219 This is obsolete, replaced by wxLog functionality.
222 Stream to associate with the debug context. Do not set this to @NULL.
224 Stream buffer to associate with the debug context.
226 void SetStream(ostream
* stream
, streambuf
* streamBuf
= NULL
);
231 // ============================================================================
232 // Global functions/macros
233 // ============================================================================
235 /** @ingroup group_funcmacro_log */
239 @deprecated Use one of the wxLogTrace() functions or one of the
240 wxVLogTrace() functions instead.
242 Calls wxTrace() with printf-style variable argument syntax. Output is
243 directed to the current output stream (see wxDebugContext).
247 #define WXTRACE(format, ...)
250 @deprecated Use one of the wxLogTrace() functions or one of the
251 wxVLogTrace() functions instead.
253 Calls wxTraceLevel with printf-style variable argument syntax. Output is
254 directed to the current output stream (see wxDebugContext). The first
255 argument should be the level at which this information is appropriate. It
256 will only be output if the level returned by wxDebugContext::GetLevel is
257 equal to or greater than this value.
261 #define WXTRACELEVEL(level, format, ...)
264 @deprecated Use one of the wxLogTrace() functions or one of the
265 wxVLogTrace() functions instead.
267 Takes printf-style variable argument syntax. Output is directed to the
268 current output stream (see wxDebugContext).
272 void wxTrace(const wxString
& format
, ...);
275 @deprecated Use one of the wxLogTrace() functions or one of the
276 wxVLogTrace() functions instead.
278 Takes @e printf() style variable argument syntax. Output is directed to the
279 current output stream (see wxDebugContext). The first argument should be
280 the level at which this information is appropriate. It will only be output
281 if the level returned by wxDebugContext::GetLevel() is equal to or greater
286 void wxTraceLevel(int level
, const wxString
& format
, ...);