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