docs/latex/wx/debugcxt.tex

   1 \section{\class{wxDebugContext}}\label{wxdebugcontext}
   2
   3 A class for performing various debugging and memory tracing
   4 operations. Full functionality (such as printing out objects
   5 currently allocated) is only present in a debugging build of wxWidgets,
   6 i.e. if the \_\_WXDEBUG\_\_ symbol is defined. wxDebugContext
   7 and related functions and macros can be compiled out by setting
   8 wxUSE\_DEBUG\_CONTEXT to 0 is setup.h
   9
  10 \wxheading{Derived from}
  11
  12 No parent class.
  13
  14 \wxheading{Include files}
  15
  16 <wx/memory.h>
  17
  18 \wxheading{Library}
  19
  20 \helpref{wxBase}{librarieslist}
  21
  22 \wxheading{See also}
  23
  24 \overview{Overview}{wxdebugcontextoverview}
  25
  26 \latexignore{\rtfignore{\wxheading{Members}}}
  27
  28 \membersection{wxDebugContext::Check}\label{wxdebugcontextcheck}
  29
  30 \func{int}{Check}{\void}
  31
  32 Checks the memory blocks for errors, starting from the currently set
  33 checkpoint.
  34
  35 \wxheading{Return value}
  36
  37 Returns the number of errors,
  38 so a value of zero represents success. Returns -1 if an error
  39 was detected that prevents further checking.
  40
  41 \membersection{wxDebugContext::Dump}\label{wxdebugcontextdump}
  42
  43 \func{bool}{Dump}{\void}
  44
  45 Performs a memory dump from the currently set checkpoint, writing to the
  46 current debug stream. Calls the {\bf Dump} member function for each wxObject
  47 derived instance.
  48
  49 \wxheading{Return value}
  50
  51 true if the function succeeded, false otherwise.
  52
  53 \membersection{wxDebugContext::GetCheckPrevious}\label{wxdebugcontextgetcheckprevious}
  54
  55 \func{bool}{GetCheckPrevious}{\void}
  56
  57 Returns true if the memory allocator checks all previous memory blocks for errors.
  58 By default, this is false since it slows down execution considerably.
  59
  60 \wxheading{See also}
  61
  62 \helpref{wxDebugContext::SetCheckPrevious}{wxdebugcontextsetcheckprevious}
  63
  64 \membersection{wxDebugContext::GetDebugMode}\label{wxdebugcontextgetdebugmode}
  65
  66 \func{bool}{GetDebugMode}{\void}
  67
  68 Returns true if debug mode is on. If debug mode is on, the wxObject new and delete
  69 operators store or use information about memory allocation. Otherwise,
  70 a straight malloc and free will be performed by these operators.
  71
  72 \wxheading{See also}
  73
  74 \helpref{wxDebugContext::SetDebugMode}{wxdebugcontextsetdebugmode}
  75
  76 \membersection{wxDebugContext::GetLevel}\label{wxdebugcontextgetlevel}
  77
  78 \func{int}{GetLevel}{\void}
  79
  80 Gets the debug level (default 1). The debug level is used by the wxTraceLevel function and
  81 the WXTRACELEVEL macro to specify how detailed the trace information is; setting
  82 a different level will only have an effect if trace statements in the application
  83 specify a value other than one.
  84
  85 This is obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
  86
  87 \wxheading{See also}
  88
  89 \helpref{wxDebugContext::SetLevel}{wxdebugcontextsetlevel}
  90
  91 \membersection{wxDebugContext::GetStream}\label{wxdebugcontextgetstream}
  92
  93 \func{ostream\&}{GetStream}{\void}
  94
  95 Returns the output stream associated with the debug context.
  96
  97 This is obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
  98
  99 \wxheading{See also}
 100
 101 \helpref{wxDebugContext::SetStream}{wxdebugcontextsetstream}
 102
 103 \membersection{wxDebugContext::GetStreamBuf}\label{wxdebugcontextgetstreambuf}
 104
 105 \func{streambuf*}{GetStreamBuf}{\void}
 106
 107 Returns a pointer to the output stream buffer associated with the debug context.
 108 There may not necessarily be a stream buffer if the stream has been set
 109 by the user.
 110
 111 This is obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
 112
 113 \membersection{wxDebugContext::HasStream}\label{wxdebugcontexthasstream}
 114
 115 \func{bool}{HasStream}{\void}
 116
 117 Returns true if there is a stream currently associated
 118 with the debug context.
 119
 120 This is obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
 121
 122 \wxheading{See also}
 123
 124 \helpref{wxDebugContext::SetStream}{wxdebugcontextsetstream}, \helpref{wxDebugContext::GetStream}{wxdebugcontextgetstream}
 125
 126 \membersection{wxDebugContext::PrintClasses}\label{wxdebugcontextprintclasses}
 127
 128 \func{bool}{PrintClasses}{\void}
 129
 130 Prints a list of the classes declared in this application, giving derivation
 131 and whether instances of this class can be dynamically created.
 132
 133 \wxheading{See also}
 134
 135 \helpref{wxDebugContext::PrintStatistics}{wxdebugcontextprintstatistics}
 136
 137 \membersection{wxDebugContext::PrintStatistics}\label{wxdebugcontextprintstatistics}
 138
 139 \func{bool}{PrintStatistics}{\param{bool}{ detailed = true}}
 140
 141 Performs a statistics analysis from the currently set checkpoint, writing
 142 to the current debug stream. The number of object and non-object
 143 allocations is printed, together with the total size.
 144
 145 \wxheading{Parameters}
 146
 147 \docparam{detailed}{If true, the function will also print how many
 148 objects of each class have been allocated, and the space taken by
 149 these class instances.}
 150
 151 \wxheading{See also}
 152
 153 \helpref{wxDebugContext::PrintStatistics}{wxdebugcontextprintstatistics}
 154
 155 \membersection{wxDebugContext::SetCheckpoint}\label{wxdebugcontextsetcheckpoint}
 156
 157 \func{void}{SetCheckpoint}{\param{bool}{ all = false}}
 158
 159 Sets the current checkpoint: Dump and PrintStatistics operations will
 160 be performed from this point on. This allows you to ignore allocations
 161 that have been performed up to this point.
 162
 163 \wxheading{Parameters}
 164
 165 \docparam{all}{If true, the checkpoint is reset to include all
 166 memory allocations since the program started.}
 167
 168 \membersection{wxDebugContext::SetCheckPrevious}\label{wxdebugcontextsetcheckprevious}
 169
 170 \func{void}{SetCheckPrevious}{\param{bool}{ check}}
 171
 172 Tells the memory allocator to check all previous memory blocks for errors.
 173 By default, this is false since it slows down execution considerably.
 174
 175 \wxheading{See also}
 176
 177 \helpref{wxDebugContext::GetCheckPrevious}{wxdebugcontextgetcheckprevious}
 178
 179 \membersection{wxDebugContext::SetDebugMode}\label{wxdebugcontextsetdebugmode}
 180
 181 \func{void}{SetDebugMode}{\param{bool}{ debug}}
 182
 183 Sets the debug mode on or off. If debug mode is on, the wxObject new and delete
 184 operators store or use information about memory allocation. Otherwise,
 185 a straight malloc and free will be performed by these operators.
 186
 187 By default, debug mode is on if \_\_WXDEBUG\_\_ is defined. If the application
 188 uses this function, it should make sure that all object memory allocated
 189 is deallocated with the same value of debug mode. Otherwise, the
 190 delete operator might try to look for memory information that does not
 191 exist.
 192
 193 \wxheading{See also}
 194
 195 \helpref{wxDebugContext::GetDebugMode}{wxdebugcontextgetdebugmode}
 196
 197 \membersection{wxDebugContext::SetFile}\label{wxdebugcontextsetfile}
 198
 199 \func{bool}{SetFile}{\param{const wxString\& }{filename}}
 200
 201 Sets the current debug file and creates a stream. This will delete any existing
 202 stream and stream buffer. By default, the debug context stream
 203 outputs to the debugger (Windows) or standard error (other platforms).
 204
 205 \membersection{wxDebugContext::SetLevel}\label{wxdebugcontextsetlevel}
 206
 207 \func{void}{SetLevel}{\param{int}{ level}}
 208
 209 Sets the debug level (default 1). The debug level is used by the wxTraceLevel function and
 210 the WXTRACELEVEL macro to specify how detailed the trace information is; setting
 211 a different level will only have an effect if trace statements in the application
 212 specify a value other than one.
 213
 214 This is obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
 215
 216 \wxheading{See also}
 217
 218 \helpref{wxDebugContext::GetLevel}{wxdebugcontextgetlevel}
 219
 220 \membersection{wxDebugContext::SetShutdownNotifyFunction}\label{wxdebugcontextsetshutdownnotifyhook}
 221
 222 \func{void}{SetShutdownNotifyFunction}{\param{wxShutdownNotifyFunction }{func}}
 223
 224 Installs a function to be called at the end of wxWidgets shutdown. It will be called after
 225 all files with global instances of wxDebugContextDumpDelayCounter have run their destructors.
 226
 227 The shutdown function must be take no parameters and return nothing.
 228
 229 \membersection{wxDebugContext::SetStandardError}\label{wxdebugcontextsetstandarderror}
 230
 231 \func{bool}{SetStandardError}{\void}
 232
 233 Sets the debugging stream to be the debugger (Windows) or standard error (other platforms).
 234 This is the default setting. The existing stream will be flushed and deleted.
 235
 236 This is obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
 237
 238 \membersection{wxDebugContext::SetStream}\label{wxdebugcontextsetstream}
 239
 240 \func{void}{SetStream}{\param{ostream* }{stream}, \param{streambuf* }{streamBuf = NULL}}
 241
 242 Sets the stream and optionally, stream buffer associated with the debug context.
 243 This operation flushes and deletes the existing stream (and stream buffer if any).
 244
 245 This is obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
 246
 247 \wxheading{Parameters}
 248
 249 \docparam{stream}{Stream to associate with the debug context. Do not set this to NULL.}
 250
 251 \docparam{streamBuf}{Stream buffer to associate with the debug context.}
 252
 253 \wxheading{See also}
 254
 255 \helpref{wxDebugContext::GetStream}{wxdebugcontextgetstream}, \helpref{wxDebugContext::HasStream}{wxdebugcontexthasstream}
 256
 257 \section{\class{wxDebugStreamBuf}}\label{wxdebugstreambuf}
 258
 259 This class allows you to treat debugging output in a similar
 260 (stream-based) fashion on different platforms. Under
 261 Windows, an ostream constructed with this buffer outputs
 262 to the debugger, or other program that intercepts debugging
 263 output. On other platforms, the output goes to standard error (cerr).
 264
 265 This is soon to be obsolete, replaced by \helpref{wxLog}{wxlog} functionality.
 266
 267 \wxheading{Derived from}
 268
 269 streambuf
 270
 271 \wxheading{Include files}
 272
 273 <wx/memory.h>
 274
 275 \wxheading{Example}
 276
 277 \begin{verbatim}
 278   wxDebugStreamBuf streamBuf;
 279   ostream stream(&streamBuf);
 280
 281   stream << "Hello world!" << endl;
 282 \end{verbatim}
 283
 284 \wxheading{See also}
 285
 286 \overview{Overview}{wxdebugcontextoverview}
 287
 288