added CentreOnScreen(), updated the docs to clear this mess a bit

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

docs/latex/wx/window.tex

@@ -143,9 +143,15 @@ A synonym for \helpref{Centre}{wxwindowcentre}.
 
 A synonym for \helpref{CentreOnParent}{wxwindowcentreonparent}.
 
+\membersection{wxWindow::CenterOnScreen}\label{wxwindowcenteronscreen}
+
+\func{void}{CenterOnScreen}{\param{int}{ direction}}
+
+A synonym for \helpref{CentreOnScreen}{wxwindowcentreonscreen}.
+
 \membersection{wxWindow::Centre}\label{wxwindowcentre}
 
-\func{void}{Centre}{\param{int}{ direction = wxHORIZONTAL}}
+\func{void}{Centre}{\param{int}{ direction = wxBOTH}}
 
 Centres the window.
 
@@ -156,7 +162,8 @@ or {\tt wxBOTH}. It may also include {\tt wxCENTRE\_ON\_SCREEN} flag
 if you want to center the window on the entire screen and not on its
 parent window.}
 
-The flag {\tt wxCENTRE\_FRAME} is obsolete and should not be used any longer.
+The flag {\tt wxCENTRE\_FRAME} is obsolete and should not be used any longer
+(it has no effect).
 
 \wxheading{Remarks}
 
@@ -169,9 +176,10 @@ centered relative to the screen anyhow.
 
 \membersection{wxWindow::CentreOnParent}\label{wxwindowcentreonparent}
 
-\func{void}{CentreOnParent}{\param{int}{ direction = wxHORIZONTAL}}
+\func{void}{CentreOnParent}{\param{int}{ direction = wxBOTH}}
 
-Centres the window.
+Centres the window on its parent. This is a more readable synonym for 
+\helpref{Centre}{wxwindowcentre}.
 
 \wxheading{Parameters}
 
@@ -187,7 +195,23 @@ window is not a top level window, then behaviour is the same as
 
 \wxheading{See also}
 
-\helpref{wxWindow::CenterOnParent}{wxwindowcenteronparent}
+\helpref{wxWindow::CentreOnScreen}{wxwindowcenteronscreen}
+
+\membersection{wxWindow::CentreOnScreen}\label{wxwindowcentreonscreen}
+
+\func{void}{CentreOnScreen}{\param{int}{ direction = wxBOTH}}
+
+Centres the window on screen. This only works for top level windows -
+otherwise, the window will still be centered on its parent.
+
+\wxheading{Parameters}
+
+\docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp
+or {\tt wxBOTH}.}
+
+\wxheading{See also}
+
+\helpref{wxWindow::CentreOnParent}{wxwindowcenteronparent}
 
 \membersection{wxWindow::Clear}\label{wxwindowclear}
 

include/wx/window.h

@@ -271,11 +271,19 @@ public:
             *h = s.y;
     }
 
-        // centre with respect to the the parent window
+        // the generic centre function - centers the window on parent by
+        // default or on screen if it doesn't have parent or
+        // wxCENTER_ON_SCREEN flag is given
     void Centre( int direction = wxBOTH );
     void Center( int direction = wxBOTH ) { Centre(direction); }
-    void CentreOnParent( int dir = wxBOTH ) { Centre(dir | wxCENTER_FRAME); }
-    void CenterOnParent( int dir = wxBOTH ) { Centre(dir | wxCENTER_FRAME); }
+
+        // centre on screen (only works for top level windows)
+    void CentreOnScreen(int dir = wxBOTH) { Centre(dir | wxCENTER_ON_SCREEN); }
+    void CenterOnScreen(int dir = wxBOTH) { CentreOnScreen(dir); }
+
+        // centre with respect to the the parent window
+    void CentreOnParent(int dir = wxBOTH) { Centre(dir | wxCENTER_FRAME); }
+    void CenterOnParent(int dir = wxBOTH) { CentreOnParent(dir); }
 
         // set window size to wrap around its children
     virtual void Fit();

src/common/wincmn.cpp

@@ -354,10 +354,11 @@ void wxWindowBase::Centre(int direction)
 
     // controls are always centered on their parent because it doesn't make
     // sense to centre them on the screen
-    if ( !(direction & wxCENTRE_ON_SCREEN) || wxDynamicCast(this, wxControl) )
+    if ( !(direction & wxCENTRE_ON_SCREEN) || !IsTopLevel() )
     {
-        // theo nly chance to get this is to have a wxControl without parent
-        wxCHECK_RET( parent, wxT("a control must have a parent") );
+        // the only chance to get this is to have a not top level window
+        // without parent which shouldn't happen
+        wxCHECK_RET( parent, wxT("this window must have a parent") );
 
         // adjust to the parents client area origin
         wxPoint posParent = parent->ClientToScreen(wxPoint(0, 0));