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