interface/log.h

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