From: Bryan Petty Date: Tue, 18 Mar 2008 01:34:57 +0000 (+0000) Subject: Finished review of Application Initialization and Termination category of functions... X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/8cd06fb5a2cfa475403c29186e69feff2c2f3c7b Finished review of Application Initialization and Termination category of functions and macros. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52601 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/app.h b/interface/app.h index 4f0baf3bfa..9f3528f638 100644 --- a/interface/app.h +++ b/interface/app.h @@ -608,14 +608,6 @@ public: // Global functions/macros // ============================================================================ -/** - The global pointer to the singleton wxApp object. - - @see wxApp::GetInstance() -*/ -wxApp *wxTheApp; - - /** @ingroup group_funcmacro_rtti */ //@{ @@ -656,41 +648,49 @@ wxApp *wxTheApp; +/** + The global pointer to the singleton wxApp object. + + @see wxApp::GetInstance() +*/ +wxApp *wxTheApp; + + + /** @ingroup group_funcmacro_appinitterm */ //@{ /** - This function doesn't exist in wxWidgets but it is created by using - the IMPLEMENT_APP() macro. + This function doesn't exist in wxWidgets but it is created by using the + IMPLEMENT_APP() macro. Thus, before using it anywhere but in the same module where this macro is used, you must make it available using DECLARE_APP(). The advantage of using this function compared to directly using the global - wxTheApp pointer is that the latter is of type wxApp* and so wouldn't - allow you to access the functions specific to your application class but not - present in wxApp while wxGetApp() returns the object of the right type. + ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't + allow you to access the functions specific to your application class but + not present in wxApp while wxGetApp() returns the object of the right type. */ -wxAppDerivedClass wxGetApp(); +wxAppDerivedClass& wxGetApp(); /** If @a doIt is @true, the fatal exceptions (also known as general protection faults under Windows or segmentation violations in the Unix world) will be caught and passed to wxApp::OnFatalException. - By default, i.e. before this function is called, they will be handled in the - normal way which usually just means that the application will be terminated. - Calling wxHandleFatalExceptions() with @a doIt equal to @false will restore - this default behaviour. + By default, i.e. before this function is called, they will be handled in + the normal way which usually just means that the application will be + terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false + will restore this default behaviour. - Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION is 1 - and under Windows platform this requires a compiler with support for SEH - (structured exception handling) which currently means only Microsoft Visual C++ - or a recent Borland C++ version. + Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION + is 1 and under Windows platform this requires a compiler with support for + SEH (structured exception handling) which currently means only Microsoft + Visual C++ or a recent Borland C++ version. */ bool wxHandleFatalExceptions(bool doIt = true); - /** This function is used in wxBase only and only if you don't create wxApp object at all. In this case you must call it from your @@ -711,6 +711,16 @@ bool wxInitialize(); */ void wxUninitialize(); +/** + This function wakes up the (internal and platform dependent) idle system, + i.e. it will force the system to send an idle event even if the system + currently @e is idle and thus would not send any idle event until after + some other event would get sent. This is also useful for sending events + between two threads and is used by the corresponding functions + wxPostEvent() and wxEvtHandler::AddPendingEvent(). +*/ +void wxWakeUpIdle(); + /** Calls wxApp::Yield. diff --git a/interface/image.h b/interface/image.h index c3ae734275..8fa1fb4fec 100644 --- a/interface/image.h +++ b/interface/image.h @@ -1467,6 +1467,9 @@ public: // Global functions/macros // ============================================================================ +/** @ingroup group_funcmacro_appinitterm */ +//@{ + /** Initializes all available image handlers. For a list of available handlers, see wxImage. @@ -1475,3 +1478,5 @@ public: */ void wxInitAllImageHandlers(); +//@} + diff --git a/interface/init.h b/interface/init.h index 2872ccc251..14e988c9a7 100644 --- a/interface/init.h +++ b/interface/init.h @@ -6,22 +6,42 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** @ingroup group_funcmacro_appinitterm */ +//@{ + /** -Free resources allocated by a successful call to wxEntryStart(). -*/ -void wxEntryCleanup(); + This function can be used to perform the initialization of wxWidgets if you + can't use the default initialization code for any reason. + If the function returns true, the initialization was successful and the + global wxApp object ::wxTheApp has been created. Moreover, wxEntryCleanup() + must be called afterwards. If the function returns false, a catastrophic + initialization error occured and (at least the GUI part of) the library + can't be used at all. -//@{ -/** - (notice that under Windows CE platform, and only there, the type of - @a pCmdLine is @c wchar_t *, otherwise it is @c char *, even in - Unicode build). + Notice that parameters @c argc and @c argv may be modified by this + function. */ bool wxEntryStart(int& argc, wxChar** argv); + +/** + See wxEntryStart(int&,wxChar**) for more info about this function. + + This is an additional overload of wxEntryStart() provided under MSW only. + It is meant to be called with the parameters passed to WinMain(). + + @note Under Windows CE platform, and only there, the type of @a pCmdLine is + @c wchar_t *, otherwise it is @c char *, even in Unicode build. +*/ bool wxEntryStart(HINSTANCE hInstance, HINSTANCE hPrevInstance = NULL, char* pCmdLine = NULL, int nCmdShow = SW_SHOWNORMAL); + +/** + Free resources allocated by a successful call to wxEntryStart(). +*/ +void wxEntryCleanup(); + //@}