clarify how top-level windows are used by wxApp (fixes #9448)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56897 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/wx/app.h b/interface/wx/app.h
index 4fea75c14b9555bcf9245d79e0ace7be1fcac068..595fe78aab983362964ae685b9384381971fc947 100644 (file)
--- a/interface/wx/app.h
+++ b/interface/wx/app.h
@@ -531,9 +531,10 @@ public:
     /**
         Returns a pointer to the top window.
 
     /**
         Returns a pointer to the top window.
 

-        @remarks If the top window hasn't been set using SetTopWindow(),
-                 this function will find the first top-level window
-                 (frame or dialog) and return that.
+        @remarks
+            If the top window hasn't been set using SetTopWindow(), this function
+            will find the first top-level window (frame or dialog or instance of
+            wxTopLevelWindow) from the internal top level window list and return that.

 
         @see SetTopWindow()
     */
 
         @see SetTopWindow()
     */


@@ -624,9 +625,13 @@ public:
         Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
         know which is the main window. You don't have to set the top window;
         it is only a convenience so that (for example) certain dialogs without parents
         Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
         know which is the main window. You don't have to set the top window;
         it is only a convenience so that (for example) certain dialogs without parents

-        can use a specific window as the top window. If no top window is specified by the
-        application, wxWidgets just uses the first frame or dialog in its top-level window
-        list, when it needs to use the top window.
+        can use a specific window as the top window.
+
+        If no top window is specified by the application, wxWidgets just uses the
+        first frame or dialog (or better, any wxTopLevelWindow) in its top-level
+        window list, when it needs to use the top window.
+        If you previously called SetTopWindow() and now you need to restore this
+        automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode.

 
         @param window
             The new top window.
 
         @param window
             The new top window.

diff --git a/interface/wx/toplevel.h b/interface/wx/toplevel.h
index 0806c2f21fed280f453ac0127ae9a18584b438c1..51aa45c6569f0f54e79ebcf4238609d25f245424 100644 (file)
--- a/interface/wx/toplevel.h
+++ b/interface/wx/toplevel.h
@@ -42,6 +42,9 @@ enum
     directly, but all of its methods are also applicable for the two classes
     above.
 
     directly, but all of its methods are also applicable for the two classes
     above.
 

+    Note that the instances of wxTopLevelWindow are managed by wxWidgets in the
+    internal top level window list.
+

     @library{wxcore}
     @category{managedwnd}
 
     @library{wxcore}
     @category{managedwnd}