X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/15b6757b26a0277472a4f6b071b52050abd922da..c8c77ee2af68bcea8ba157b4d5a4e2cd5b4912bd:/docs/doxygen/overviews/exceptions.h diff --git a/docs/doxygen/overviews/exceptions.h b/docs/doxygen/overviews/exceptions.h index 68e753d213..83192f0cf0 100644 --- a/docs/doxygen/overviews/exceptions.h +++ b/docs/doxygen/overviews/exceptions.h @@ -1,76 +1,97 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: exceptions +// Name: exceptions.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! - - @page exceptions_overview C++ exceptions overview - - #Introduction - @ref exceptionstrategies_overview - #Technicalities - - - @section exceptionintroduction Introduction - - wxWidgets had been started long before the exceptions were introduced in C++ so - it is not very surprising that it is not built around using them as some more - modern C++ libraries are. For instance, the library doesn't throw exceptions to - signal about the errors. Moreover, up to (and including) the version 2.4 of - wxWidgets, even using the exceptions in the user code was dangerous because the - library code wasn't exception-safe and so an exception propagating through it - could result in memory and/or resource leaks, and also not very convenient. - Starting from the version 2.5.1 wxWidgets becomes more exception-friendly. It - still doesn't use the exceptions by itself but it should be now safe to use the - exceptions in the user code and the library tries to help you with this. Please - note that making the library exception-safe is still work in progress. - - - @section exceptionstrategies Strategies for exceptions handling - - There are several choice for using the exceptions in wxWidgets programs. First - of all, you may not use them at all. As stated above, the library doesn't throw - any exceptions by itself and so you don't have to worry about exceptions at all - unless your own code throws them. This is, of course, the simplest solution but - may be not the best one to deal with all possible errors. - Another strategy is to use exceptions only to signal truly fatal errors. In - this case you probably don't expect to recover from them and the default - behaviour -- to simply terminate the program -- may be appropriate. If it is - not, you may override #OnUnhandledException() - in your wxApp-derived class to perform any clean up tasks. Note, however, that - any information about the exact exception type is lost when this function is - called, so if you need you should override #OnRun() and - add a try/catch clause around the call of the base class version. This would - allow you to catch any exceptions generated during the execution of the main - event loop. To deal with the exceptions which may arise during the program - startup and/or shutdown you should insert try/catch clauses in - #OnInit() and/or #OnExit() as well. - Finally, you may also want to continue running even when certain exceptions - occur. If all of your exceptions may happen only in the event handlers of a - single class (or only in the classes derived from it), you may centralize your - exception handling code in #ProcessEvent - method of this class. If this is impractical, you may also consider overriding - the wxApp::HandleEvent() which allows you to handle - all the exceptions thrown by any event handler. - - - @section exceptionstechnicalities Technicalities - - To use any kind of exception support in the library you need to build it with - @c wxUSE_EXCEPTIONS set to 1. This should be the case by default but - if it isn't, you should edit the @c include/wx/msw/setup.h file under - Windows or run @c configure with @c --enable-exceptions argument - under Unix. - On the other hand, if you do not plan to use exceptions, setting this - flag to 0 or using @c --disable-exceptions could result in a leaner and - slightly faster library. - As for any other library feature, there is a #sample - showing how to use it. Please look at its sources for further information. - - */ - - +/** + +@page overview_exceptions C++ Exceptions + +@li @ref overview_exceptions_introduction +@li @ref overview_exceptions_strategies +@li @ref overview_exceptions_tech + + +
+ + +@section overview_exceptions_introduction Introduction + +wxWidgets had been started long before the exceptions were introduced in C++ so +it is not very surprising that it is not built around using them as some more +modern C++ libraries are. For instance, the library doesn't throw exceptions to +signal about the errors. Moreover, up to (and including) the version 2.4 of +wxWidgets, even using the exceptions in the user code was dangerous because the +library code wasn't exception-safe and so an exception propagating through it +could result in memory and/or resource leaks, and also not very convenient. + +However the recent wxWidgets versions are exception-friendly. This means that +while the library still doesn't use the exceptions by itself, it should be now +safe to use the exceptions in the user code and the library tries to help you +with this. + + +@section overview_exceptions_strategies Strategies for exceptions handling + +There are several choice for using the exceptions in wxWidgets programs. First +of all, you may not use them at all. As stated above, the library doesn't throw +any exceptions by itself and so you don't have to worry about exceptions at all +unless your own code throws them. This is, of course, the simplest solution but +may be not the best one to deal with all possible errors. + +The next simplest strategy is to only use exceptions inside non-GUI code, i.e. +never let unhandled exceptions escape the event handler in which it happened. +In this case using exceptions in wxWidgets programs is not different from using +them in any other C++ program. + +Things get more interesting if you decide to let (at least some) exceptions +escape from the event handler in which they occurred. Such exceptions will be +caught by wxWidgets and the special wxApp::OnExceptionInMainLoop() method will +be called from the @c catch clause. This allows you to decide in a single place +what to do about such exceptions: you may want to handle the exception somehow +or terminate the program. In this sense, OnExceptionInMainLoop() is equivalent +to putting a @c try/catch block around the entire @c main() function body in +the traditional console programs. However notice that, as its name indicates, +this method won't help you with the exceptions thrown before the main loop is +started or after it is over, so you may still want to have @c try/catch in your +overridden wxApp::OnInit() and wxApp::OnExit() methods too, otherwise +wxApp::OnUnhandledException() will be called. + +Finally, notice that even if you decide to not let any exceptions escape in +this way, this still may happen unexpectedly in a program using exceptions as a +result of a bug. So consider always overriding OnExceptionInMainLoop() in your +wxApp-derived class if you use exceptions in your program, whether you expect +it to be called or not. In the latter case you may simple re-throw the +exception and let it bubble up to OnUnhandledException() as well. + +To summarize, when you use exceptions in your code, you may handle them in the +following places, in order of priority: + -# In a @c try/catch block inside an event handler. + -# In wxApp::OnExceptionInMainLoop(). + -# In wxApp::OnUnhandledException(). + +In the first two cases you may decide whether you want to handle the exception +and continue execution or to exit the program. In the last one the program is +about to exit already so you can just try to save any unsaved data and notify +the user about the problem (while being careful not to throw any more +exceptions as otherwise @c std::terminate() will be called). + + +@section overview_exceptions_tech Technicalities + +To use any kind of exception support in the library you need to build it +with @c wxUSE_EXCEPTIONS set to 1. It is turned on by default but you may +wish to check @c include/wx/msw/setup.h file under Windows or run @c configure +with explicit @c --enable-exceptions argument under Unix. + +On the other hand, if you do not plan to use exceptions, setting this +flag to 0 or using @c --disable-exceptions could result in a leaner and +slightly faster library. + +As for any other library feature, there is a sample (@c except) +showing how to use it. Please look at its sources for further information. + +*/