Remove calls to wxApp::SetTopWindow() from the samples and documentation.

It is definitely not necessary to call SetTopWindow() when there is only a
single top level window and it is arguable whether it's useful to do it even
when there are many of them so don't encourage its use in the documentation
and also remove all its occurrences from the samples.

Closes #12816.

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

demos/life/life.cpp

@@ -163,9 +163,8 @@ bool LifeApp::OnInit()
     // create the main application window
     LifeFrame *frame = new LifeFrame();
 
-    // show it and tell the application that it's our main window
+    // show it
     frame->Show(true);
-    SetTopWindow(frame);
 
     // just for Motif
 #ifdef __WXMOTIF__

docs/doxygen/overviews/app.h

@@ -27,8 +27,7 @@ the wxApp::OnInit member defined for a class derived from wxApp.
 @e OnInit will usually create a top window as a bare minimum. Unlike in earlier
 versions of wxWidgets, OnInit does not return a frame. Instead it returns a
 boolean value which indicates whether processing should continue (@true) or not
-(@false). You call wxApp::SetTopWindow to let wxWidgets know about the top
+(@false).
-window.
 
 Note that the program's command line arguments, represented by @e argc and
 @e argv, are available from within wxApp member functions.
@@ -59,7 +58,6 @@ bool DerivedApp::OnInit()
     wxFrame *the_frame = new wxFrame(NULL, ID_MYFRAME, argv[0]);
     ...
     the_frame->Show(true);
-    SetTopWindow(the_frame);
 
     return true;
 }

docs/doxygen/overviews/helloworld.h

@@ -124,7 +124,6 @@ bool MyApp::OnInit()
 {
     MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
     frame->Show( true );
-    SetTopWindow( frame );
     return true;
 }
 @endcode

docs/doxygen/overviews/python.h

@@ -206,8 +206,6 @@ python DialogUnits.py
 62:         frame = MyFrame(NULL, -1, "This is a test")
 63:         frame.Show(true)
 64:
-65:         # Tell wxWidgets that this is our main window
-66:         self.SetTopWindow(frame)
 67:
 68:         # Return a success flag
 69:         return true
@@ -257,8 +255,7 @@ Destroy() method as shown on line 36.
 
 Just like wxWidgets in C++, wxPython apps need to create a class derived from
 @c wxApp (line 56) that implements a method named @c OnInit, (line 59.) This
-method should create the application's main window (line 62) and use
+method should create the application's main window (line 62) and show it.
-wxApp.SetTopWindow() (line 66) to inform wxWidgets about it.
 
 And finally, at line 72 an instance of the application class is created. At
 this point wxPython finishes initializing itself, and calls the @c OnInit

samples/animate/anitest.cpp

@@ -102,8 +102,6 @@ bool MyApp::OnInit()
                                  wxDEFAULT_FRAME_STYLE);
     frame->Show(true);
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/aui/auidemo.cpp

@@ -570,7 +570,6 @@ bool MyApp::OnInit()
                                  wxT("wxAUI Sample Application"),
                                  wxDefaultPosition,
                                  wxSize(800, 600));
-    SetTopWindow(frame);
     frame->Show();
 
     return true;

samples/config/conftest.cpp

@@ -119,7 +119,6 @@ bool MyApp::OnInit()
     // create the main program window
     MyFrame *frame = new MyFrame;
     frame->Show(true);
-    SetTopWindow(frame);
 
     // use our config object...
     if ( pConfig->Read(wxT("/Controls/Check"), 1l) != 0 ) {

samples/dataview/dataview.cpp

@@ -242,7 +242,6 @@ bool MyApp::OnInit()
 
     MyFrame *frame =
         new MyFrame(NULL, "wxDataViewCtrl sample", 40, 40, 1000, 540);
-    SetTopWindow(frame);
 
     frame->Show(true);
     return true;

samples/dialup/nettest.cpp

@@ -161,9 +161,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(wxT("Dial-up wxWidgets demo"),
                                  wxPoint(50, 50), wxSize(450, 340));
 
-    // Show it and tell the application that it's our main window
+    // Show it
     frame->Show(true);
-    SetTopWindow(frame);
 
     // Init dial up manager
     m_dial = wxDialUpManager::Create();

samples/docview/docview.cpp

@@ -231,7 +231,6 @@ bool MyApp::OnInit()
     frame->Centre();
     frame->Show();
 
-    SetTopWindow(frame);
     return true;
 }
 

samples/drawing/drawing.cpp

@@ -347,9 +347,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(wxT("Drawing sample"),
                                  wxDefaultPosition, wxSize(550, 840));
 
-    // Show it and tell the application that it's our main window
+    // Show it
     frame->Show(true);
-    SetTopWindow(frame);
 
     if ( !LoadImages() )
     {

samples/exec/exec.cpp

@@ -413,9 +413,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(wxT("Exec wxWidgets sample"),
                                  wxDefaultPosition, wxSize(500, 140));
 
-    // Show it and tell the application that it's our main window
+    // Show it
     frame->Show(true);
-    SetTopWindow(frame);
 
     // success: wxApp::OnRun() will be called which will enter the main message
     // loop and the application will run. If we returned false here, the

samples/font/font.cpp

@@ -282,9 +282,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(wxT("Font wxWidgets demo"),
                                  wxPoint(50, 50), wxSize(600, 400));
 
-    // Show it and tell the application that it's our main window
+    // Show it
     frame->Show(true);
-    SetTopWindow(frame);
 
     // success: wxApp::OnRun() will be called which will enter the main message
     // loop and the application will run. If we returned 'false' here, the

samples/help/demo.cpp

@@ -324,7 +324,6 @@ bool MyApp::OnInit()
 #endif // !USE_SIMPLE_HELP_PROVIDER
 
     frame->Show(true);
-    SetTopWindow(frame);
 
     // initialise the help system: this means that we'll use doc.hlp file under
     // Windows and that the HTML docs are in the subdirectory doc for platforms

samples/html/help/help.cpp

@@ -127,11 +127,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(_("HTML Help Sample"),
         wxDefaultPosition, wxDefaultSize);
 
-    // Show it and tell the application that it's our main window
+    // Show it
-    // @@@ what does it do exactly, in fact? is it necessary here?
     frame->Show(true);
-    SetTopWindow(frame);
-
 
     // success: wxApp::OnRun() will be called which will enter the main message
     // loop and the application will run. If we returned false here, the

samples/html/printing/printing.cpp

@@ -152,11 +152,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(_("Printing test"),
         wxDefaultPosition, wxSize(640, 480));
 
-    // Show it and tell the application that it's our main window
+    // Show it
-    // @@@ what does it do exactly, in fact? is it necessary here?
     frame->Show(true);
-    SetTopWindow(frame);
-
 
     // success: wxApp::OnRun() will be called which will enter the main message
     // loop and the application will run. If we returned false here, the

samples/html/virtual/virtual.cpp

@@ -169,10 +169,9 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(_("wxHtmlWindow testing application"),
         wxDefaultPosition, wxSize(640, 480));
 
-    // Show it and tell the application that it's our main window
+    // Show it
-    // @@@ what does it do exactly, in fact? is it necessary here?
     frame->Show(true);
-    SetTopWindow(frame);
+
     wxFileSystem::AddHandler(new MyVFS);
 
     // success: wxApp::OnRun() will be called which will enter the main message

samples/html/widget/widget.cpp

@@ -162,10 +162,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame( _("wxHtmlWindow testing application"),
         wxDefaultPosition, wxSize(640, 480) );
 
-    // Show it and tell the application that it's our main window
+    // Show it
-    // @@@ what does it do exactly, in fact? is it necessary here?
     frame->Show(true);
-    SetTopWindow(frame);
 
     // success: wxApp::OnRun() will be called which will enter the main message
     // loop and the application will run. If we returned false here, the

samples/html/zip/zip.cpp

@@ -123,10 +123,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(_("wxHtmlWindow testing application"),
         wxDefaultPosition, wxSize(640, 480) );
 
-    // Show it and tell the application that it's our main window
+    // Show it
-    // @@@ what does it do exactly, in fact? is it necessary here?
     frame->Show(true);
-    SetTopWindow(frame);
 
     // success: wxApp::OnRun() will be called which will enter the main message
     // loop and the application will run. If we returned false here, the

samples/internat/internat.cpp

@@ -271,7 +271,6 @@ bool MyApp::OnInit()
 
     // Show the frame
     frame->Show(true);
-    SetTopWindow(frame);
 
     return true;
 }

samples/joytest/joytest.cpp

@@ -89,8 +89,6 @@ bool MyApp::OnInit()
     frame->CenterOnScreen();
     frame->Show(true);
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/listctrl/listtest.cpp

@@ -100,8 +100,6 @@ bool MyApp::OnInit()
     // Show the frame
     frame->Show(true);
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/menu/menu.cpp

@@ -365,8 +365,6 @@ bool MyApp::OnInit()
     frame->SetStatusText(wxT("Welcome to wxWidgets menu sample"));
 #endif // wxUSE_STATUSBAR
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/nativdlg/nativdlg.cpp

@@ -67,9 +67,6 @@ bool MyApp::OnInit(void)
   frame->panel = new wxWindow(frame, wxID_ANY, wxPoint(0, 0), wxSize(400, 400), 0, wxT("MyMainFrame"));
   frame->Show(true);
 
-  // Return the main frame window
-  SetTopWindow(frame);
-
   return true;
 }
 

samples/notebook/notebook.cpp

@@ -47,7 +47,6 @@ bool MyApp::OnInit()
 
     // Create the main window
     MyFrame *frame = new MyFrame();
-    SetTopWindow(frame);
 
     // Problem with generic wxNotebook implementation whereby it doesn't size
     // properly unless you set the size again

samples/oleauto/oleauto.cpp

@@ -132,10 +132,8 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame(wxT("OleAuto wxWidgets App"),
                                  wxPoint(50, 50), wxSize(450, 340));
 
-    // Show it and tell the application that it's our main window
+    // Show it
-    // @@@ what does it do exactly, in fact? is it necessary here?
     frame->Show(true);
-    SetTopWindow(frame);
 
     // success: wxApp::OnRun() will be called which will enter the main message
     // loop and the application will run. If we returned false here, the

samples/opengl/isosurf/isosurf.cpp

@@ -57,7 +57,7 @@ bool MyApp::OnInit()
         return false;
 
     // Create the main frame window
-    SetTopWindow(new MyFrame(NULL, wxT("wxWidgets OpenGL Isosurf Sample")));
+    MyFrame *frame = new MyFrame(NULL, wxT("wxWidgets OpenGL Isosurf Sample"));
 
     return true;
 }

samples/ownerdrw/ownerdrw.cpp

@@ -97,8 +97,6 @@ bool OwnerDrawnApp::OnInit(void)
         = new OwnerDrawnFrame(NULL, wxT("wxWidgets Ownerdraw Sample"),
                               50, 50, 450, 340);
 
-    SetTopWindow(pFrame);
-
     return true;
 }
 

samples/printing/printing.cpp

@@ -123,8 +123,6 @@ bool MyApp::OnInit(void)
     frame->Centre(wxBOTH);
     frame->Show();
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/regtest/regtest.cpp

@@ -326,8 +326,6 @@ bool RegApp::OnInit()
     RegFrame *frame = new RegFrame(NULL, wxT("wxRegTest"), 50, 50, 600, 350);
     frame->Show(true);
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/ribbon/ribbondemo.cpp

@@ -139,7 +139,6 @@ bool MyApp::OnInit()
         return false;
 
     wxFrame* frame = new MyFrame;
-    SetTopWindow(frame);
     frame->Show();
 
     return true;

samples/sashtest/sashtest.cpp

@@ -79,8 +79,6 @@ bool MyApp::OnInit(void)
 
   frame->Show(true);
 
-  SetTopWindow(frame);
-
   return true;
 }
 

samples/sockets/client.cpp

@@ -190,9 +190,8 @@ bool MyApp::OnInit()
   // Create the main application window
   MyFrame *frame = new MyFrame();
 
-  // Show it and tell the application that it's our main window
+  // Show it
   frame->Show(true);
-  SetTopWindow(frame);
 
   // success
   return true;

samples/sockets/server.cpp

@@ -162,9 +162,8 @@ bool MyApp::OnInit()
   // Create the main application window
   MyFrame *frame = new MyFrame();
 
-  // Show it and tell the application that it's our main window
+  // Show it
   frame->Show(true);
-  SetTopWindow(frame);
 
   // Success
   return true;

samples/stc/stctest.cpp

@@ -226,7 +226,6 @@ bool App::OnInit () {
     // open application frame
     m_frame->Layout ();
     m_frame->Show (true);
-    SetTopWindow (m_frame);
 
     return true;
 }

samples/svg/svgtest.cpp

@@ -160,8 +160,6 @@ bool MyApp::OnInit()
 
     frame->Show(true);
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/text/text.cpp

@@ -545,8 +545,6 @@ bool MyApp::OnInit()
 
     frame->Show(true);
 
-    SetTopWindow(frame);
-
     // report success
     return true;
 }

samples/toolbar/toolbar.cpp

@@ -315,8 +315,6 @@ bool MyApp::OnInit()
 
     wxInitAllImageHandlers();
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/treectrl/treetest.cpp

@@ -198,7 +198,6 @@ bool MyApp::OnInit()
 
     // Show the frame
     frame->Show(true);
-    SetTopWindow(frame);
 
     return true;
 }

samples/typetest/typetest.cpp

@@ -116,8 +116,6 @@ bool MyApp::OnInit()
     // Show the frame
     frame->Show(true);
 
-    SetTopWindow(frame);
-
     return true;
 }
 

samples/validate/validate.cpp

@@ -136,7 +136,7 @@ bool MyApp::OnInit()
     MyFrame *frame = new MyFrame((wxFrame *) NULL, wxT("Validator Test"),
                                  50, 50, 300, 250);
     frame->Show(true);
-    SetTopWindow(frame);
+
     return true;
 }