Finished review of Application Initialization and Termination category of functions...

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 4f0baf3bfa7df4e89abe7409bebc59f794f43e47..9f3528f638504b04e239453ecae52fcbb85dff79 100644 (file)
--- a/interface/app.h
+++ b/interface/app.h
@@ -608,14 +608,6 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/**
-    The global pointer to the singleton wxApp object.
-
-    @see wxApp::GetInstance()
-*/
-wxApp *wxTheApp;
-
-

 
 /** @ingroup group_funcmacro_rtti */
 //@{
 
 /** @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 */
 //@{
 
 /**
 /** @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
 
     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.
 
 
 /**
     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);
 
 */
 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
 /**
     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();
 
 */
 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.
 
 /**
     Calls wxApp::Yield.
 

diff --git a/interface/image.h b/interface/image.h
index c3ae734275fb5a5b711718f726f13eb4f301dbe5..8fa1fb4fec4c357423ce81b3526240e88569413d 100644 (file)
--- a/interface/image.h
+++ b/interface/image.h
@@ -1467,6 +1467,9 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_appinitterm */
+//@{
+

 /**
     Initializes all available image handlers. For a list of available handlers,
     see wxImage.
 /**
     Initializes all available image handlers. For a list of available handlers,
     see wxImage.


@@ -1475,3 +1478,5 @@ public:
 */
 void wxInitAllImageHandlers();
 
 */
 void wxInitAllImageHandlers();
 

+//@}
+

diff --git a/interface/init.h b/interface/init.h
index 2872ccc25154a969b8ae886854e30cfdcfe828f0..14e988c9a79f735568eebb3eed6442442cf5b1c0 100644 (file)
--- a/interface/init.h
+++ b/interface/init.h
@@ -6,22 +6,42 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // 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);
 */
 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);
 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();
+

 //@}
 
 //@}