docs/doxygen/overviews/exceptions.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        exceptions.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_exceptions C++ Exceptions
  12
  13 @li @ref overview_exceptions_introduction
  14 @li @ref overview_exceptions_strategies
  15 @li @ref overview_exceptions_tech
  16
  17
  18 <hr>
  19
  20
  21 @section overview_exceptions_introduction Introduction
  22
  23 wxWidgets had been started long before the exceptions were introduced in C++ so
  24 it is not very surprising that it is not built around using them as some more
  25 modern C++ libraries are. For instance, the library doesn't throw exceptions to
  26 signal about the errors. Moreover, up to (and including) the version 2.4 of
  27 wxWidgets, even using the exceptions in the user code was dangerous because the
  28 library code wasn't exception-safe and so an exception propagating through it
  29 could result in memory and/or resource leaks, and also not very convenient.
  30
  31 wxWidgets is exception-friendly.
  32 It still doesn't use the exceptions by itself but it should be now safe to use the
  33 exceptions in the user code and the library tries to help you with this. Please
  34 note that making the library exception-safe is still work in progress.
  35
  36
  37 @section overview_exceptions_strategies Strategies for exceptions handling
  38
  39 There are several choice for using the exceptions in wxWidgets programs. First
  40 of all, you may not use them at all. As stated above, the library doesn't throw
  41 any exceptions by itself and so you don't have to worry about exceptions at all
  42 unless your own code throws them. This is, of course, the simplest solution but
  43 may be not the best one to deal with all possible errors.
  44
  45 Another strategy is to use exceptions only to signal truly fatal errors. In
  46 this case you probably don't expect to recover from them and the default
  47 behaviour -- to simply terminate the program -- may be appropriate. If it is
  48 not, you may override wxApp::OnUnhandledException()
  49 in your wxApp-derived class to perform any clean up tasks. Note, however, that
  50 any information about the exact exception type is lost when this function is
  51 called, so if you need you should override wxApp::OnRun() and
  52 add a try/catch clause around the call of the base class version. This would
  53 allow you to catch any exceptions generated during the execution of the main
  54 event loop. To deal with the exceptions which may arise during the program
  55 startup and/or shutdown you should insert try/catch clauses in
  56 wxApp::OnInit() and/or wxApp::OnExit() as well.
  57
  58 Finally, you may also want to continue running even when certain exceptions
  59 occur. If all of your exceptions may happen only in the event handlers of a
  60 single class (or only in the classes derived from it), you may centralize your
  61 exception handling code in wxApp::ProcessEvent
  62 method of this class. If this is impractical, you may also consider overriding
  63 the wxApp::HandleEvent() which allows you to handle
  64 all the exceptions thrown by any event handler.
  65
  66
  67 @section overview_exceptions_tech Technicalities
  68
  69 To use any kind of exception support in the library you need to build it
  70 with @c wxUSE_EXCEPTIONS set to 1. This should be the case by default but
  71 if it isn't, you should edit the @c include/wx/msw/setup.h file under
  72 Windows or run @c configure with @c --enable-exceptions argument
  73 under Unix.
  74
  75 On the other hand, if you do not plan to use exceptions, setting this
  76 flag to 0 or using @c --disable-exceptions could result in a leaner and
  77 slightly faster library.
  78
  79 As for any other library feature, there is a sample (@c except)
  80 showing how to use it. Please look at its sources for further information.
  81
  82 */