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 However the recent wxWidgets versions are exception-friendly. This means that
  32 while the library still doesn't use the exceptions by itself, it should be now
  33 safe to use the exceptions in the user code and the library tries to help you
  34 with this.
  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 The next simplest strategy is to only use exceptions inside non-GUI code, i.e.
  46 never let unhandled exceptions escape the event handler in which it happened.
  47 In this case using exceptions in wxWidgets programs is not different from using
  48 them in any other C++ program.
  49
  50 Things get more interesting if you decide to let (at least some) exceptions
  51 escape from the event handler in which they occurred. Such exceptions will be
  52 caught by wxWidgets and the special wxApp::OnExceptionInMainLoop() method will
  53 be called from the @c catch clause. This allows you to decide in a single place
  54 what to do about such exceptions: you may want to handle the exception somehow
  55 or terminate the program. In this sense, OnExceptionInMainLoop() is equivalent
  56 to putting a @c try/catch block around the entire @c main() function body in
  57 the traditional console programs. However notice that, as its name indicates,
  58 this method won't help you with the exceptions thrown before the main loop is
  59 started or after it is over, so you may still want to have @c try/catch in your
  60 overridden wxApp::OnInit() and wxApp::OnExit() methods too, otherwise
  61 wxApp::OnUnhandledException() will be called.
  62
  63 Finally, notice that even if you decide to not let any exceptions escape in
  64 this way, this still may happen unexpectedly in a program using exceptions as a
  65 result of a bug. So consider always overriding OnExceptionInMainLoop() in your
  66 wxApp-derived class if you use exceptions in your program, whether you expect
  67 it to be called or not. In the latter case you may simple re-throw the
  68 exception and let it bubble up to OnUnhandledException() as well.
  69
  70 To summarize, when you use exceptions in your code, you may handle them in the
  71 following places, in order of priority:
  72     -# In a @c try/catch block inside an event handler.
  73     -# In wxApp::OnExceptionInMainLoop().
  74     -# In wxApp::OnUnhandledException().
  75
  76 In the first two cases you may decide whether you want to handle the exception
  77 and continue execution or to exit the program. In the last one the program is
  78 about to exit already so you can just try to save any unsaved data and notify
  79 the user about the problem (while being careful not to throw any more
  80 exceptions as otherwise @c std::terminate() will be called).
  81
  82
  83 @section overview_exceptions_tech Technicalities
  84
  85 To use any kind of exception support in the library you need to build it
  86 with @c wxUSE_EXCEPTIONS set to 1. It is turned on by default but you may
  87 wish to check @c include/wx/msw/setup.h file under Windows or run @c configure
  88 with explicit @c --enable-exceptions argument under Unix.
  89
  90 On the other hand, if you do not plan to use exceptions, setting this
  91 flag to 0 or using @c --disable-exceptions could result in a leaner and
  92 slightly faster library.
  93
  94 As for any other library feature, there is a sample (@c except)
  95 showing how to use it. Please look at its sources for further information.
  96
  97 */