1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: log.tex 3%% Purpose: wxLog and related classes documentation 4%% Author: Vadim Zeitlin 5%% Modified by: 6%% Created: some time ago 7%% RCS-ID: $Id: log.tex 46579 2007-06-21 12:34:32Z JS $ 8%% Copyright: (c) 1997-2001 Vadim Zeitlin 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxLog}}\label{wxlog} 13 14wxLog class defines the interface for the {\it log targets} used by wxWidgets 15logging functions as explained in the \helpref{wxLog overview}{wxlogoverview}. 16The only situations when you need to directly use this class is when you want 17to derive your own log target because the existing ones don't satisfy your 18needs. Another case is if you wish to customize the behaviour of the standard 19logging classes (all of which respect the wxLog settings): for example, set 20which trace messages are logged and which are not or change (or even remove 21completely) the timestamp on the messages. 22 23Otherwise, it is completely hidden behind the {\it wxLogXXX()} functions and 24you may not even know about its existence. 25 26See \helpref{log overview}{wxlogoverview} for the descriptions of wxWidgets 27logging facilities. 28 29\wxheading{Derived from} 30 31No base class 32 33\wxheading{Include files} 34 35<wx/log.h> 36 37\latexignore{\rtfignore{\wxheading{Function groups}}} 38 39\membersection{Global functions} 40 41The functions in this section work with and manipulate the active log target. 42The \helpref{OnLog()}{wxlogonlog} is called by the {\it wxLogXXX()} functions 43and invokes the \helpref{DoLog()}{wxlogdolog} of the active log target if any. 44Get/Set methods are used to install/query the current active target and, 45finally, \helpref{DontCreateOnDemand()}{wxlogdontcreateondemand} disables the 46automatic creation of a standard log target if none actually exists. It is 47only useful when the application is terminating and shouldn't be used in other 48situations because it may easily lead to a loss of messages. 49 50\helpref{OnLog}{wxlogonlog}\\ 51\helpref{GetActiveTarget}{wxloggetactivetarget}\\ 52\helpref{SetActiveTarget}{wxlogsetactivetarget}\\ 53\helpref{DontCreateOnDemand}{wxlogdontcreateondemand}\\ 54\helpref{Suspend}{wxlogsuspend}\\ 55\helpref{Resume}{wxlogresume} 56 57\membersection{Logging functions}\label{loggingfunctions} 58 59There are two functions which must be implemented by any derived class to 60actually process the log messages: \helpref{DoLog}{wxlogdolog} and 61\helpref{DoLogString}{wxlogdologstring}. The second function receives a string 62which just has to be output in some way and the easiest way to write a new log 63target is to override just this function in the derived class. If more control 64over the output format is needed, then the first function must be overridden 65which allows to construct custom messages depending on the log level or even 66do completely different things depending on the message severity (for example, 67throw away all messages except warnings and errors, show warnings on the 68screen and forward the error messages to the user's (or programmer's) cell 69phone - maybe depending on whether the timestamp tells us if it is day or 70night in the current time zone). 71 72There also functions to support message buffering. Why are they needed? 73Some of wxLog implementations, most notably the standard wxLogGui class, 74buffer the messages (for example, to avoid showing the user a zillion of modal 75message boxes one after another -- which would be really annoying). 76\helpref{Flush()}{wxlogflush} shows them all and clears the buffer contents. 77This function doesn't do anything if the buffer is already empty. 78 79\helpref{Flush}{wxlogflush}\\ 80\helpref{FlushActive}{wxlogflushactive} 81 82\membersection{Customization}\label{wxlogcustomization} 83 84The functions below allow some limited customization of wxLog behaviour 85without writing a new log target class (which, aside of being a matter of 86several minutes, allows you to do anything you want). 87 88The verbose messages are the trace messages which are not disabled in the 89release mode and are generated by \helpref{wxLogVerbose}{wxlogverbose}. They 90are not normally shown to the user because they present little interest, but 91may be activated, for example, in order to help the user find some program 92problem. 93 94As for the (real) trace messages, their handling depends on the settings of 95the (application global) {\it trace mask}. There are two ways to specify it: 96either by using \helpref{SetTraceMask}{wxlogsettracemask} and 97\helpref{GetTraceMask}{wxloggettracemask} and using 98\helpref{wxLogTrace}{wxlogtrace} which takes an integer mask or by using 99\helpref{AddTraceMask}{wxlogaddtracemask} for string trace masks. 100 101The difference between bit-wise and string trace masks is that a message using 102integer trace mask will only be logged if all bits of the mask are set in the 103current mask while a message using string mask will be logged simply if the 104mask had been added before to the list of allowed ones. 105 106For example, 107 108\begin{verbatim} 109// wxTraceOleCalls is one of standard bit masks 110wxLogTrace(wxTraceRefCount | wxTraceOleCalls, "Active object ref count: %d", nRef); 111\end{verbatim} 112will do something only if the current trace mask contains both 113{\tt wxTraceRefCount} and {\tt wxTraceOle}, but 114 115\begin{verbatim} 116// wxTRACE_OleCalls is one of standard string masks 117wxLogTrace(wxTRACE_OleCalls, "IFoo::Bar() called"); 118\end{verbatim} 119 120will log the message if it was preceded by 121 122\begin{verbatim} 123wxLog::AddTraceMask(wxTRACE_OleCalls); 124\end{verbatim} 125 126Using string masks is simpler and allows to easily add custom ones, so this is 127the preferred way of working with trace messages. The integer trace mask is 128kept for compatibility and for additional (but very rarely needed) flexibility 129only. 130 131The standard trace masks are given in \helpref{wxLogTrace}{wxlogtrace} 132documentation. 133 134Finally, the {\it wxLog::DoLog()} function automatically prepends a time stamp 135to all the messages. The format of the time stamp may be changed: it can be 136any string with \% specifications fully described in the documentation of the 137standard {\it strftime()} function. For example, the default format is 138"[\%d/\%b/\%y \%H:\%M:\%S] " which gives something like "[17/Sep/98 22:10:16] " 139(without quotes) for the current date. Setting an empty string as the time 140format disables timestamping of the messages completely. 141 142{\bf NB:} Timestamping is disabled for Visual C++ users in debug builds by 143default because otherwise it would be impossible to directly go to the line 144from which the log message was generated by simply clicking in the debugger 145window on the corresponding error message. If you wish to enable it, please use 146\helpref{SetTimestamp}{wxlogsettimestamp} explicitly. 147 148\helpref{AddTraceMask}{wxlogaddtracemask}\\ 149\helpref{RemoveTraceMask}{wxlogremovetracemask}\\ 150\helpref{ClearTraceMasks}{wxlogcleartracemasks}\\ 151\helpref{GetTraceMasks}{wxloggettracemasks}\\ 152\helpref{IsAllowedTraceMask}{wxlogisallowedtracemask}\\ 153\helpref{SetVerbose}{wxlogsetverbose}\\ 154\helpref{GetVerbose}{wxloggetverbose}\\ 155\helpref{SetTimestamp}{wxlogsettimestamp}\\ 156\helpref{GetTimestamp}{wxloggettimestamp}\\ 157\helpref{SetTraceMask}{wxlogsettracemask}\\ 158\helpref{GetTraceMask}{wxloggettracemask}\\ 159\helpref{SetRepetitionCounting}{wxlogsetrepetitioncounting}\\ 160\helpref{GetRepetitionCounting}{wxloggetrepetitioncounting} 161 162%%%%% MEMBERS HERE %%%%% 163\helponly{\insertatlevel{2}{ 164 165\wxheading{Members} 166 167}} 168 169\membersection{wxLog::AddTraceMask}\label{wxlogaddtracemask} 170 171\func{static void}{AddTraceMask}{\param{const wxString\& }{mask}} 172 173Add the {\it mask} to the list of allowed masks for 174\helpref{wxLogTrace}{wxlogtrace}. 175 176\wxheading{See also} 177 178\helpref{RemoveTraceMask}{wxlogremovetracemask} 179\helpref{GetTraceMasks}{wxloggettracemasks} 180 181\membersection{wxLog::ClearTraceMasks}\label{wxlogcleartracemasks} 182 183\func{static void}{ClearTraceMasks}{\void} 184 185Removes all trace masks previously set with 186\helpref{AddTraceMask}{wxlogaddtracemask}. 187 188\wxheading{See also} 189 190\helpref{RemoveTraceMask}{wxlogremovetracemask} 191 192\membersection{wxLog::GetTraceMasks}\label{wxloggettracemasks} 193 194\func{static const wxArrayString \&}{GetTraceMasks}{\void} 195 196Returns the currently allowed list of string trace masks. 197 198\wxheading{See also} 199 200\helpref{AddTraceMask}{wxlogaddtracemask}. 201 202\membersection{wxLog::OnLog}\label{wxlogonlog} 203 204\func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}} 205 206Forwards the message at specified level to the {\it DoLog()} function of the 207active log target if there is any, does nothing otherwise. 208 209\membersection{wxLog::GetActiveTarget}\label{wxloggetactivetarget} 210 211\func{static wxLog *}{GetActiveTarget}{\void} 212 213Returns the pointer to the active log target (may be NULL). 214 215\membersection{wxLog::SetActiveTarget}\label{wxlogsetactivetarget} 216 217\func{static wxLog *}{SetActiveTarget}{\param{wxLog * }{ logtarget}} 218 219Sets the specified log target as the active one. Returns the pointer to the 220previous active log target (may be NULL). To suppress logging use a new 221instance of wxLogNull not NULL. If the active log target is set to NULL a 222new default log target will be created when logging occurs. 223 224\membersection{wxLog::Suspend}\label{wxlogsuspend} 225 226\func{static void}{Suspend}{\void} 227 228Suspends the logging until \helpref{Resume}{wxlogresume} is called. Note that 229the latter must be called the same number of times as the former to undo it, 230i.e. if you call Suspend() twice you must call Resume() twice as well. 231 232Note that suspending the logging means that the log sink won't be be flushed 233periodically, it doesn't have any effect if the current log target does the 234logging immediately without waiting for \helpref{Flush}{wxlogflush} to be 235called (the standard GUI log target only shows the log dialog when it is 236flushed, so Suspend() works as expected with it). 237 238\wxheading{See also} 239 240\helpref{Resume}{wxlogresume},\\ 241\helpref{wxLogNull}{wxlogoverview} 242 243\membersection{wxLog::Resume}\label{wxlogresume} 244 245\func{static void}{Resume}{\void} 246 247Resumes logging previously suspended by a call to 248\helpref{Suspend}{wxlogsuspend}. All messages logged in the meanwhile will be 249flushed soon. 250 251\membersection{wxLog::DoLog}\label{wxlogdolog} 252 253\func{virtual void}{DoLog}{\param{wxLogLevel }{level}, \param{const wxChar }{*msg}, \param{time\_t }{timestamp}} 254 255Called to process the message of the specified severity. {\it msg} is the text 256of the message as specified in the call of {\it wxLogXXX()} function which 257generated it and {\it timestamp} is the moment when the message was generated. 258 259The base class version prepends the timestamp to the message, adds a prefix 260corresponding to the log level and then calls 261\helpref{DoLogString}{wxlogdologstring} with the resulting string. 262 263\membersection{wxLog::DoLogString}\label{wxlogdologstring} 264 265\func{virtual void}{DoLogString}{\param{const wxChar }{*msg}, \param{time\_t }{timestamp}} 266 267Called to log the specified string. The timestamp is already included into the 268string but still passed to this function. 269 270A simple implementation may just send the string to {\tt stdout} or, better, 271{\tt stderr}. 272 273\membersection{wxLog::DontCreateOnDemand}\label{wxlogdontcreateondemand} 274 275\func{static void}{DontCreateOnDemand}{\void} 276 277Instructs wxLog to not create new log targets on the fly if there is none 278currently. (Almost) for internal use only: it is supposed to be called by the 279application shutdown code. 280 281Note that this function also calls 282\helpref{ClearTraceMasks}{wxlogcleartracemasks}. 283 284\membersection{wxLog::Flush}\label{wxlogflush} 285 286\func{virtual void}{Flush}{\void} 287 288Shows all the messages currently in buffer and clears it. If the buffer 289is already empty, nothing happens. 290 291\membersection{wxLog::FlushActive}\label{wxlogflushactive} 292 293\func{static void}{FlushActive}{\void} 294 295Flushes the current log target if any, does nothing if there is none. 296 297\wxheading{See also} 298 299\helpref{Flush}{wxlogflush} 300 301\membersection{wxLog::SetVerbose}\label{wxlogsetverbose} 302 303\func{static void}{SetVerbose}{\param{bool }{ verbose = true}} 304 305Activates or deactivates verbose mode in which the verbose messages are 306logged as the normal ones instead of being silently dropped. 307 308\membersection{wxLog::GetVerbose}\label{wxloggetverbose} 309 310\func{static bool}{GetVerbose}{\void} 311 312Returns whether the verbose mode is currently active. 313 314\membersection{wxLog::SetLogLevel}\label{wxlogsetloglevel} 315 316\func{static void}{SetLogLevel}{\param{wxLogLevel }{ logLevel}} 317 318Specifies that log messages with $level > logLevel$ should be ignored 319and not sent to the active log target. 320 321\membersection{wxLog::GetLogLevel}\label{wxloggetloglevel} 322 323\func{static wxLogLevel}{GetLogLevel}{\void} 324 325Returns the current log level limit. 326 327\membersection{wxLog::SetRepetitionCounting}\label{wxlogsetrepetitioncounting} 328 329\func{static void}{SetRepetitionCounting}{\param{bool }{ repetCounting = true}} 330 331Enables logging mode in which a log message is logged once, and in case exactly 332the same message successively repeats one or more times, only the number of 333repetitions is logged. 334 335\membersection{wxLog::GetRepetitionCounting}\label{wxloggetrepetitioncounting} 336 337\func{static bool}{GetRepetitionCounting}{\void} 338 339Returns whether the repetition counting mode is enabled. 340 341 342\membersection{wxLog::SetTimestamp}\label{wxlogsettimestamp} 343 344\func{void}{SetTimestamp}{\param{const char * }{ format}} 345 346Sets the timestamp format prepended by the default log targets to all 347messages. The string may contain any normal characters as well as \% 348prefixed format specificators, see {\it strftime()} manual for details. 349Passing a NULL value (not empty string) to this function disables message timestamping. 350 351\membersection{wxLog::GetTimestamp}\label{wxloggettimestamp} 352 353\constfunc{const char *}{GetTimestamp}{\void} 354 355Returns the current timestamp format string. 356 357\membersection{wxLog::SetTraceMask}\label{wxlogsettracemask} 358 359\func{static void}{SetTraceMask}{\param{wxTraceMask }{ mask}} 360 361Sets the trace mask, see \helpref{Customization}{wxlogcustomization} 362section for details. 363 364\membersection{wxLog::GetTraceMask}\label{wxloggettracemask} 365 366Returns the current trace mask, see \helpref{Customization}{wxlogcustomization} section 367for details. 368 369\membersection{wxLog::IsAllowedTraceMask}\label{wxlogisallowedtracemask} 370 371\func{static bool}{IsAllowedTraceMask}{\param{const wxChar *}{mask}} 372 373Returns true if the {\it mask} is one of allowed masks for 374\helpref{wxLogTrace}{wxlogtrace}. 375 376See also: \helpref{AddTraceMask}{wxlogaddtracemask}, 377\helpref{RemoveTraceMask}{wxlogremovetracemask} 378 379\membersection{wxLog::RemoveTraceMask}\label{wxlogremovetracemask} 380 381\func{static void}{RemoveTraceMask}{\param{const wxString\& }{mask}} 382 383Remove the {\it mask} from the list of allowed masks for 384\helpref{wxLogTrace}{wxlogtrace}. 385 386See also: \helpref{AddTraceMask}{wxlogaddtracemask} 387 388%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogChain %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 389 390\section{\class{wxLogChain}}\label{wxlogchain} 391 392This simple class allows to chain log sinks, that is to install a new sink but 393keep passing log messages to the old one instead of replacing it completely as 394\helpref{SetActiveTarget}{wxlogsetactivetarget} does. 395 396It is especially useful when you want to divert the logs somewhere (for 397example to a file or a log window) but also keep showing the error messages 398using the standard dialogs as \helpref{wxLogGui}{wxlogoverview} does by default. 399 400Example of usage: 401 402\begin{verbatim} 403wxLogChain *logChain = new wxLogChain(new wxLogStderr); 404 405// all the log messages are sent to stderr and also processed as usually 406... 407 408// don't delete logChain directly as this would leave a dangling 409// pointer as active log target, use SetActiveTarget() instead 410delete wxLog::SetActiveTarget(...something else or NULL...); 411 412\end{verbatim} 413 414\wxheading{Derived from} 415 416\helpref{wxLog}{wxlog} 417 418\wxheading{Include files} 419 420<wx/log.h> 421 422\latexignore{\rtfignore{\wxheading{Members}}} 423 424\membersection{wxLogChain::wxLogChain}\label{wxlogchainctor} 425 426\func{}{wxLogChain}{\param{wxLog *}{logger}} 427 428Sets the specified {\tt logger} (which may be {\tt NULL}) as the default log 429target but the log messages are also passed to the previous log target if any. 430 431\membersection{wxLogChain::\destruct{wxLogChain}}\label{wxlogchaindtor} 432 433\func{}{\destruct{wxLogChain}}{\void} 434 435Destroys the previous log target. 436 437\membersection{wxLogChain::DetachOldLog}\label{wxlogchaindetacholdlog} 438 439\func{void}{DetachOldLog}{\void} 440 441Detaches the old log target so it won't be destroyed when the wxLogChain object 442is destroyed. 443 444\membersection{wxLogChain::GetOldLog}\label{wxlogchaingetoldlog} 445 446\constfunc{wxLog *}{GetOldLog}{\void} 447 448Returns the pointer to the previously active log target (which may be {\tt 449NULL}). 450 451\membersection{wxLogChain::IsPassingMessages}\label{wxlogchainispassingmessages} 452 453\constfunc{bool}{IsPassingMessages}{\void} 454 455Returns {\tt true} if the messages are passed to the previously active log 456target (default) or {\tt false} if \helpref{PassMessages}{wxlogchainpassmessages} 457had been called. 458 459\membersection{wxLogChain::PassMessages}\label{wxlogchainpassmessages} 460 461\func{void}{PassMessages}{\param{bool }{passMessages}} 462 463By default, the log messages are passed to the previously active log target. 464Calling this function with {\tt false} parameter disables this behaviour 465(presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and 466it can be reenabled by calling it again with {\it passMessages} set to {\tt 467true}. 468 469\membersection{wxLogChain::SetLog}\label{wxlogchainsetlog} 470 471\func{void}{SetLog}{\param{wxLog *}{logger}} 472 473Sets another log target to use (may be {\tt NULL}). The log target specified 474in the \helpref{constructor}{wxlogchainctor} or in a previous call to 475this function is deleted. 476 477This doesn't change the old log target value (the one the messages are 478forwarded to) which still remains the same as was active when wxLogChain 479object was created. 480 481%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogGui %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 482 483\section{\class{wxLogGui}}\label{wxloggui} 484 485This is the default log target for the GUI wxWidgets applications. It is passed 486to \helpref{wxLog::SetActiveTarget}{wxlogsetactivetarget} at the program 487startup and is deleted by wxWidgets during the program shut down. 488 489\wxheading{Derived from} 490 491\helpref{wxLog}{wxlog} 492 493\wxheading{Include files} 494 495<wx/log.h> 496 497\latexignore{\rtfignore{\wxheading{Members}}} 498 499\membersection{wxLogGui::wxLogGui}\label{wxlogguictor} 500 501\func{}{wxLogGui}{\void} 502 503Default constructor. 504 505%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogNull %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 506 507\section{\class{wxLogNull}}\label{wxlognull} 508 509This class allows to temporarily suspend logging. All calls to the log 510functions during the life time of an object of this class are just ignored. 511 512In particular, it can be used to suppress the log messages given by wxWidgets 513itself but it should be noted that it is rarely the best way to cope with this 514problem as {\bf all} log messages are suppressed, even if they indicate a 515completely different error than the one the programmer wanted to suppress. 516 517For instance, the example of the overview: 518 519{\small 520\begin{verbatim} 521 wxFile file; 522 523 // wxFile.Open() normally complains if file can't be opened, we don't want it 524 { 525 wxLogNull logNo; 526 if ( !file.Open("bar") ) 527 ... process error ourselves ... 528 } // ~wxLogNull called, old log sink restored 529 530 wxLogMessage("..."); // ok 531\end{verbatim} 532}% 533 534would be better written as: 535 536{\small 537\begin{verbatim} 538 wxFile file; 539 540 // don't try to open file if it doesn't exist, we are prepared to deal with 541 // this ourselves - but all other errors are not expected 542 if ( wxFile::Exists("bar") ) 543 { 544 // gives an error message if the file couldn't be opened 545 file.Open("bar"); 546 } 547 else 548 { 549 ... 550 } 551\end{verbatim} 552}% 553 554\wxheading{Derived from} 555 556\helpref{wxLog}{wxlog} 557 558\wxheading{Include files} 559 560<wx/log.h> 561 562\latexignore{\rtfignore{\wxheading{Members}}} 563 564\membersection{wxLogNull::wxLogNull}\label{wxlognullctor} 565 566\func{}{wxLogNull}{\void} 567 568Suspends logging. 569 570\membersection{wxLogNull::\destruct{wxLogNull}}\label{wxlognulldtor} 571 572Resumes logging. 573 574%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogPassThrough %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 575 576\section{\class{wxLogPassThrough}}\label{wxlogpassthrough} 577 578A special version of \helpref{wxLogChain}{wxlogchain} which uses itself as the 579new log target. Maybe more clearly, it means that this is a log target which 580forwards the log messages to the previously installed one in addition to 581processing them itself. 582 583Unlike \helpref{wxLogChain}{wxlogchain} which is usually used directly as is, 584this class must be derived from to implement \helpref{DoLog}{wxlogdolog} 585and/or \helpref{DoLogString}{wxlogdologstring} methods. 586 587\wxheading{Derived from} 588 589\helpref{wxLogChain}{wxlogchain} 590 591\wxheading{Include files} 592 593<wx/log.h> 594 595\latexignore{\rtfignore{\wxheading{Members}}} 596 597\membersection{wxLogPassThrough::wxLogPassThrough}\label{wxlogpassthroughctor} 598 599Default ctor installs this object as the current active log target. 600 601%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogStderr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 602 603\section{\class{wxLogStderr}}\label{wxlogstderr} 604 605This class can be used to redirect the log messages to a C file stream (not to 606be confused with C++ streams). It is the default log target for the non-GUI 607wxWidgets applications which send all the output to {\tt stderr}. 608 609\wxheading{Derived from} 610 611\helpref{wxLog}{wxlog} 612 613\wxheading{Include files} 614 615<wx/log.h> 616 617\wxheading{See also} 618 619\helpref{wxLogStream}{wxlogstream} 620 621\latexignore{\rtfignore{\wxheading{Members}}} 622 623\membersection{wxLogStderr::wxLogStderr}\label{wxlogstderrctor} 624 625\func{}{wxLogStderr}{\param{FILE }{*fp = NULL}} 626 627Constructs a log target which sends all the log messages to the given 628{\tt FILE}. If it is {\tt NULL}, the messages are sent to {\tt stderr}. 629 630%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogStream %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 631 632\section{\class{wxLogStream}}\label{wxlogstream} 633 634This class can be used to redirect the log messages to a C++ stream. 635 636Please note that this class is only available if wxWidgets was compiled with 637the standard iostream library support ({\tt wxUSE\_STD\_IOSTREAM} must be on). 638 639\wxheading{Derived from} 640 641\helpref{wxLog}{wxlog} 642 643\wxheading{Include files} 644 645<wx/log.h> 646 647\wxheading{See also} 648 649\helpref{wxLogStderr}{wxlogstderr},\\ 650\helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} 651 652\latexignore{\rtfignore{\wxheading{Members}}} 653 654\membersection{wxLogStream::wxLogStream}\label{wxlogstreamctor} 655 656\func{}{wxLogStream}{\param{std::ostream }{*ostr = NULL}} 657 658Constructs a log target which sends all the log messages to the given 659output stream. If it is {\tt NULL}, the messages are sent to {\tt cerr}. 660 661%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 662 663\section{\class{wxLogTextCtrl}}\label{wxlogtextctrl} 664 665Using these target all the log messages can be redirected to a text control. 666The text control must have been created with {\tt wxTE\_MULTILINE} style by the 667caller previously. 668 669\wxheading{Derived from} 670 671\helpref{wxLog}{wxlog} 672 673\wxheading{Include files} 674 675<wx/log.h> 676 677\wxheading{See also} 678 679\helpref{wxTextCtrl}{wxtextctrl},\\ 680\helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} 681 682\latexignore{\rtfignore{\wxheading{Members}}} 683 684\membersection{wxLogTextCtrl::wxLogTextCtrl}\label{wxlogtextctrlctor} 685 686\func{}{wxLogTextCtrl}{\param{wxTextCtrl }{*textctrl}} 687 688Constructs a log target which sends all the log messages to the given text 689control. The {\it textctrl} parameter cannot be {\tt NULL}. 690 691%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogWindow %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 692 693\section{\class{wxLogWindow}}\label{wxlogwindow} 694 695This class represents a background log window: to be precise, it collects all 696log messages in the log frame which it manages but also passes them on to the 697log target which was active at the moment of its creation. This allows, for 698example, to show all the log messages in a frame but still continue to process 699them normally by showing the standard log dialog. 700 701\wxheading{Derived from} 702 703\helpref{wxLogPassThrough}{wxlogpassthrough} 704 705\wxheading{Include files} 706 707<wx/log.h> 708 709\wxheading{See also} 710 711\helpref{wxLogTextCtrl}{wxlogtextctrl} 712 713\latexignore{\rtfignore{\wxheading{Members}}} 714 715\membersection{wxLogWindow::wxLogWindow}\label{wxlogwindowctor} 716 717\func{}{wxLogWindow}{\param{wxFrame }{*parent}, \param{const wxChar }{*title}, \param{bool }{show = {\tt true}}, \param{bool }{passToOld = {\tt true}}} 718 719Creates the log frame window and starts collecting the messages in it. 720 721\wxheading{Parameters} 722 723\docparam{parent}{The parent window for the log frame, may be {\tt NULL}} 724 725\docparam{title}{The title for the log frame} 726 727\docparam{show}{{\tt true} to show the frame initially (default), otherwise 728\helpref{wxLogWindow::Show}{wxlogwindowshow} must be called later.} 729 730\docparam{passToOld}{{\tt true} to process the log messages normally in addition to 731logging them in the log frame (default), {\tt false} to only log them in the 732log frame.} 733 734\membersection{wxLogWindow::Show}\label{wxlogwindowshow} 735 736\func{void}{Show}{\param{bool }{show = {\tt true}}} 737 738Shows or hides the frame. 739 740\membersection{wxLogWindow::GetFrame}\label{wxlogwindowgetframe} 741 742\constfunc{wxFrame *}{GetFrame}{\void} 743 744Returns the associated log frame window. This may be used to position or resize 745it but use \helpref{wxLogWindow::Show}{wxlogwindowshow} to show or hide it. 746 747\membersection{wxLogWindow::OnFrameCreate}\label{wxlogwindowonframecreate} 748 749\func{virtual void}{OnFrameCreate}{\param{wxFrame }{*frame}} 750 751Called immediately after the log frame creation allowing for 752any extra initializations. 753 754\membersection{wxLogWindow::OnFrameClose}\label{wxlogwindowonframeclose} 755 756\func{virtual bool}{OnFrameClose}{\param{wxFrame }{*frame}} 757 758Called if the user closes the window interactively, will not be 759called if it is destroyed for another reason (such as when program 760exits). 761 762Return {\tt true} from here to allow the frame to close, {\tt false} to 763prevent this from happening. 764 765\wxheading{See also} 766 767\helpref{wxLogWindow::OnFrameDelete}{wxlogwindowonframedelete} 768 769\membersection{wxLogWindow::OnFrameDelete}\label{wxlogwindowonframedelete} 770 771\func{virtual void}{OnFrameDelete}{\param{wxFrame }{*frame}} 772 773Called right before the log frame is going to be deleted: will 774always be called unlike \helpref{OnFrameClose()}{wxlogwindowonframeclose}. 775 776