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

interface/wx/app.h

@@ -531,9 +531,10 @@ public:
     /**
         Returns a pointer to the top window.
 
-        @remarks If the top window hasn't been set using SetTopWindow(),
+        @remarks
-                 this function will find the first top-level window
+            If the top window hasn't been set using SetTopWindow(), this function
-                 (frame or dialog) and return that.
+            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()
     */
@@ -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
-        can use a specific window as the top window. If no top window is specified by the
+        can use a specific window as the top window.
-        application, wxWidgets just uses the first frame or dialog in its top-level window
+
-        list, when it needs to use 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.

interface/wx/toplevel.h

@@ -42,6 +42,9 @@ enum
     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}