X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e25cd7750c571191ce69438de5f7c0293d1b5270..23efa4bfb9104d6ef947a217efa80b2bc5bf9e76:/interface/wx/window.h

diff --git a/interface/wx/window.h b/interface/wx/window.h
index 62b402c0e1..71b0f46344 100644
--- a/interface/wx/window.h
+++ b/interface/wx/window.h
@@ -207,8 +207,9 @@ enum wxUpdateUI
            Under Windows, puts a query button on the caption. When pressed,
            Windows will go into a context-sensitive help mode and wxWidgets
            will send a wxEVT_HELP event if the user clicked on an application window.
-           This style cannot be used together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so
-           these two styles are automatically turned of if this one is used.
+           This style cannot be used (because of the underlying native behaviour)
+           together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
+           are automatically turned off if this one is used.
     @style{wxWS_EX_PROCESS_IDLE}
            This window should always process idle events, even if the mode set
            by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.
@@ -269,7 +270,7 @@ public:
         @see @ref overview_windowdeletion "Window Deletion Overview",
              Destroy(), wxCloseEvent
     */
-    ~wxWindow();
+    virtual ~wxWindow();
 
     /**
         This method may be overridden in the derived classes to return @false to
@@ -319,7 +320,7 @@ public:
 
         @remarks This function is currently only implemented under Mac/Carbon.
     */
-    void AlwaysShowScrollbars(bool hflag, bool vflag);
+    virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
 
     /**
         Sets the cached best size value.
@@ -331,7 +332,7 @@ public:
         SetTransparent() may succeed. If this function returns @false, transparent
         windows are definitely not supported by the current system.
     */
-    bool CanSetTransparent();
+    virtual bool CanSetTransparent();
 
     /**
         Directs all mouse input to this window.
@@ -349,17 +350,17 @@ public:
 
         @see ReleaseMouse(), wxMouseCaptureLostEvent
     */
-    virtual void CaptureMouse();
+    void CaptureMouse();
 
     /**
         A synonym for Centre().
     */
-    void Center(int direction);
+    void Center(int dir = wxBOTH);
 
     /**
         A synonym for CentreOnParent().
     */
-    void CenterOnParent(int direction);
+    void CenterOnParent(int dir = wxBOTH);
 
     /**
         Centres the window.
@@ -397,9 +398,8 @@ public:
         Clears the window by filling it with the current background colour. Does not
         cause an erase background event to be generated.
     */
-    void ClearBackground();
+    virtual void ClearBackground();
 
-    //@{
     /**
         Converts to screen coordinates from coordinates relative to this window.
 
@@ -409,8 +409,6 @@ public:
         @param y
             A pointer to a integer value for the y coordinate. Pass the client
             coordinate in, and a screen coordinate will be passed out.
-        @param pt
-            The client position for the second form of the function.
 
         @beginWxPythonOnly
         In place of a single overloaded method name, wxPython implements the following methods:
@@ -419,8 +417,14 @@ public:
         @endWxPythonOnly
     */
     void ClientToScreen(int* x, int* y) const;
+
+    /**
+        Converts to screen coordinates from coordinates relative to this window.
+
+        @param pt
+            The client position for the second form of the function.
+    */
     wxPoint ClientToScreen(const wxPoint& pt) const;
-    //@}
 
     /**
         Converts client area size @a size to corresponding window size.
@@ -436,7 +440,7 @@ public:
 
         @see WindowToClientSize()
     */
-    virtual wxSize ClientToWindowSize(const wxSize& size);
+    virtual wxSize ClientToWindowSize(const wxSize& size) const;
 
     /**
         Converts window size @a size to corresponding client area size
@@ -452,7 +456,7 @@ public:
 
         @see ClientToWindowSize()
     */
-    virtual wxSize WindowToClientSize(const wxSize& size);
+    virtual wxSize WindowToClientSize(const wxSize& size) const;
 
     /**
         This function simply generates a wxCloseEvent whose handler usually tries
@@ -542,7 +546,7 @@ public:
     /**
         Destroys all children of a window. Called automatically by the destructor.
     */
-    virtual void DestroyChildren();
+    bool DestroyChildren();
 
     /**
         Returns true if this window is in process of being destroyed.
@@ -566,27 +570,6 @@ public:
     */
     bool Disable();
 
-    /**
-        Gets the size which best suits the window: for a control, it would be
-        the minimal size which doesn't truncate the control, for a panel - the
-        same size as it would have after a call to Fit().
-
-        The default implementation of this function is designed for use in container
-        windows, such as wxPanel, and works something like this:
-        -# If the window has a sizer then it is used to calculate the best size.
-        -# Otherwise if the window has layout constraints then those are used to
-           calculate the best size.
-        -# Otherwise if the window has children then the best size is set to be large
-           enough to show all the children.
-        -# Otherwise if there are no children then the window's minimal size will be
-           used as its best size.
-        -# Otherwise if there is no minimal size set, then the current size is used
-           for the best size.
-
-        @see @ref overview_windowsizing
-    */
-    virtual wxSize DoGetBestSize() const;
-
     /**
         Does the window-specific updating after processing the update event.
         This function is called by UpdateWindowUI() in order to check return
@@ -618,7 +601,11 @@ public:
             If @true, the window is eligible for drop file events.
             If @false, the window will not accept drop file events.
 
-        @remarks Windows only.
+        @remarks Windows only until version 2.8.9, available on all platforms
+                 since 2.8.10. Cannot be used together with SetDropTarget() on
+                 non-Windows platforms.
+
+        @see SetDropTarget()
     */
     virtual void DragAcceptFiles(bool accept);
 
@@ -670,7 +657,7 @@ public:
 
         @see FindWindow()
     */
-    static wxWindow* FindWindowById(long id, wxWindow* parent = NULL);
+    static wxWindow* FindWindowById(long id, const wxWindow* parent = 0);
 
     /**
         Find a window by its label.
@@ -684,10 +671,10 @@ public:
         @see FindWindow()
     */
     static wxWindow* FindWindowByLabel(const wxString& label,
-                                       wxWindow* parent = NULL);
+                                       const wxWindow* parent = 0);
 
     /**
-        Find a window by its name (as given in a window constructor or @b Create
+        Find a window by its name (as given in a window constructor or Create()
         function call).
 
         If @a parent is @NULL, the search will start from all top-level frames
@@ -700,7 +687,7 @@ public:
         @see FindWindow()
     */
     static wxWindow* FindWindowByName(const wxString& name,
-                                      wxWindow* parent = NULL);
+                                      const wxWindow* parent = 0);
 
     /**
         Sizes the window so that it fits around its subwindows.
@@ -750,12 +737,12 @@ public:
 
         @see wxWindowUpdateLocker, Thaw(), IsFrozen()
     */
-    virtual void Freeze();
+    void Freeze();
 
     /**
         Gets the accelerator table for this window. See wxAcceleratorTable.
     */
-    wxAcceleratorTable* GetAcceleratorTable() const;
+    wxAcceleratorTable* GetAcceleratorTable();
 
     /**
         Returns the accessible object for this window, if any.
@@ -763,12 +750,6 @@ public:
     */
     wxAccessible* GetAccessible();
 
-    /**
-        @deprecated
-        This method is deprecated, use GetEffectiveMinSize() instead.
-    */
-    wxSize GetAdjustedBestSize() const;
-
     /**
         Returns the background colour of the window.
 
@@ -857,16 +838,12 @@ public:
     //@{
     /**
         Returns the size of the window 'client area' in pixels.
+
         The client area is the area which may be drawn on by the programmer,
         excluding title bar, border, scrollbars, etc.
         Note that if this window is a top-level one and it is currently minimized, the
         return size is empty (both width and height are 0).
 
-        @param width
-            Receives the client width in pixels.
-        @param height
-            Receives the client height in pixels.
-
         @see GetSize(), GetVirtualSize()
     */
     void GetClientSize(int* width, int* height) const;
@@ -912,7 +889,7 @@ public:
 
         @see SetDropTarget(), @ref overview_dnd
     */
-    wxDropTarget* GetDropTarget() const;
+    virtual wxDropTarget* GetDropTarget() const;
 
     /**
         Merges the window's best size into the min size and returns the result.
@@ -954,7 +931,7 @@ public:
         @see SetForegroundColour(), SetBackgroundColour(),
              GetBackgroundColour()
     */
-    wxColour GetForegroundColour();
+    wxColour GetForegroundColour() const;
 
     /**
         Returns the grandparent of a window, or @NULL if there isn't one.
@@ -966,7 +943,7 @@ public:
         Cast it to an appropriate handle, such as @b HWND for Windows,
         @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
     */
-    void* GetHandle() const;
+    virtual WXWidget GetHandle() const;
 
     /**
         Gets the help text to be used as context-sensitive help for this window.
@@ -975,7 +952,7 @@ public:
 
         @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider
     */
-    virtual wxString GetHelpText() const;
+    wxString GetHelpText() const;
 
     /**
         Gets the help text to be used as context-sensitive help for this window.
@@ -987,7 +964,7 @@ public:
         @param origin
             Help event origin, see also wxHelpEvent::GetOrigin.
     */
-    virtual wxString GetHelpTextAtPoint(const wxPoint point,
+    virtual wxString GetHelpTextAtPoint(const wxPoint& point,
                                         wxHelpEvent::Origin origin) const;
 
     /**
@@ -999,7 +976,7 @@ public:
 
         @see SetId(), @ref overview_windowids
     */
-    int GetId() const;
+    wxWindowID GetId() const;
 
     /**
         Generic way of getting a label from any window, for
@@ -1023,7 +1000,7 @@ public:
 
         @see GetMaxSize()
     */
-    wxSize GetMaxClientSize() const;
+    virtual wxSize GetMaxClientSize() const;
 
     /**
         Returns the maximum size of the window.
@@ -1033,7 +1010,7 @@ public:
 
         @see GetMaxClientSize()
     */
-    wxSize GetMaxSize() const;
+    virtual wxSize GetMaxSize() const;
 
     /**
         Returns the minimum size of window's client area, an indication to the sizer
@@ -1081,32 +1058,37 @@ public:
     /**
         Returns the parent of the window, or @NULL if there is no parent.
     */
-    virtual wxWindow* GetParent() const;
+    wxWindow* GetParent() const;
 
     //@{
     /**
         This function shows a popup menu at the given position in this window and
-        returns the selected id. It can be more convenient than the general purpose
-        PopupMenu() function for simple menus proposing a choice in a list of
-        strings to the user.
+        returns the selected id.
 
-        @param menu
-            The menu to show
-        @param pos
-            The position at which to show the menu in client coordinates
-        @param x
-            The horizontal position of the menu
-        @param y
-            The vertical position of the menu
+        It can be more convenient than the general purpose PopupMenu() function
+        for simple menus proposing a choice in a list of strings to the user.
+
+        Notice that to avoid unexpected conflicts between the (usually
+        consecutive range of) ids used by the menu passed to this function and
+        the existing EVT_UPDATE_UI() handlers, this function temporarily
+        disables UI updates for the window, so you need to manually disable
+        (or toggle or ...) any items which should be disabled in the menu
+        before showing it.
+
+        The parameter @a menu is the menu to show.
+        The parameter @a pos (or the parameters @a x and @a y) is the
+        position at which to show the menu in client coordinates.
 
-        @return The selected menu item id or wxID_NONE if none selected or an
-                 error occurred.
+        @return
+             The selected menu item id or @c wxID_NONE if none selected or an
+             error occurred.
+
+        @since 2.9.0
     */
     int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos);
     int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y);
     //@}
 
-    //@{
     /**
         This gets the position of the window in pixels, relative to the parent window
         for the child windows or relative to the display origin for the top level windows.
@@ -1119,8 +1101,14 @@ public:
         @see GetScreenPosition()
     */
     void GetPosition(int* x, int* y) const;
+
+    /**
+        This gets the position of the window in pixels, relative to the parent window
+        for the child windows or relative to the display origin for the top level windows.
+
+        @see GetScreenPosition()
+    */
     wxPoint GetPosition() const;
-    //@}
 
     /**
         Returns the previous window before this one among the parent children or @c
@@ -1139,7 +1127,6 @@ public:
     */
     wxRect GetRect() const;
 
-    //@{
     /**
         Returns the window position in screen coordinates, whether the window is a
         child window or a top level one.
@@ -1152,8 +1139,14 @@ public:
         @see GetPosition()
     */
     void GetScreenPosition(int* x, int* y) const;
+
+    /**
+        Returns the window position in screen coordinates, whether the window is a
+        child window or a top level one.
+
+        @see GetPosition()
+    */
     wxPoint GetScreenPosition() const;
-    //@}
 
     /**
         Returns the position and size of the window on the screen as a wxRect object.
@@ -1167,23 +1160,22 @@ public:
 
         @see See SetScrollbar()
     */
-    virtual int GetScrollPos(int orientation);
+    virtual int GetScrollPos(int orientation) const;
 
     /**
         Returns the built-in scrollbar range.
 
         @see SetScrollbar()
     */
-    virtual int GetScrollRange(int orientation);
+    virtual int GetScrollRange(int orientation) const;
 
     /**
         Returns the built-in scrollbar thumb size.
 
         @see SetScrollbar()
     */
-    virtual int GetScrollThumb(int orientation);
+    virtual int GetScrollThumb(int orientation) const;
 
-    //@{
     /**
         Returns the size of the entire window in pixels, including title bar, border,
         scrollbars, etc.
@@ -1199,8 +1191,11 @@ public:
         @see GetClientSize(), GetVirtualSize()
     */
     void GetSize(int* width, int* height) const;
+
+    /**
+        See the GetSize(int*,int*) overload for more info.
+    */
     wxSize GetSize() const;
-    //@}
 
     /**
         Return the sizer associated with the window by a previous call to
@@ -1208,7 +1203,6 @@ public:
     */
     wxSizer* GetSizer() const;
 
-    //@{
     /**
         Gets the dimensions of the string as it would be drawn on the
         window with the currently selected font.
@@ -1227,21 +1221,17 @@ public:
             Return value for external leading (optional).
         @param font
             Font to use instead of the current window font (optional).
-        @param use16
-            If @true, string contains 16-bit characters. The default is @false.
     */
     virtual void GetTextExtent(const wxString& string, int* w, int* h,
                                int* descent = NULL,
                                int* externalLeading = NULL,
-                               const wxFont* font = NULL,
-                               bool use16 = false) const;
+                               const wxFont* font = NULL) const;
 
     /**
         Gets the dimensions of the string as it would be drawn on the
         window with the currently selected font.
     */
     wxSize  GetTextExtent(const wxString& string) const;
-    //@}
 
     /**
         Get the associated tooltip or @NULL if none.
@@ -1254,19 +1244,24 @@ public:
 
         @see wxRegion, wxRegionIterator
     */
-    virtual wxRegion GetUpdateRegion() const;
+    const wxRegion& GetUpdateRegion() const;
 
     /**
         Returns a pointer to the current validator for the window, or @NULL if
         there is none.
     */
-    wxValidator* GetValidator() const;
+    virtual wxValidator* GetValidator();
 
     //@{
     /**
         This gets the virtual size of the window in pixels.
         By default it returns the client size of the window, but after a call to
-        SetVirtualSize() it will return that size.
+        SetVirtualSize() it will return the size set with that method.
+    */
+    wxSize GetVirtualSize() const;
+
+    /**
+        Like the other GetVirtualSize() overload but uses pointers instead.
 
         @param width
             Receives the window virtual width.
@@ -1274,20 +1269,22 @@ public:
             Receives the window virtual height.
     */
     void GetVirtualSize(int* width, int* height) const;
-    wxSize GetVirtualSize() const;
     //@}
 
     /**
         Returns the size of the left/right and top/bottom borders of this window in x
         and y components of the result respectively.
     */
-    wxSize GetWindowBorderSize() const;
+    virtual wxSize GetWindowBorderSize() const;
 
+    //@{
     /**
-        Gets the window style that was passed to the constructor or @b Create
-        method. @b GetWindowStyle() is another name for the same function.
+        Gets the window style that was passed to the constructor or Create()
+        method. GetWindowStyle() is another name for the same function.
     */
-    long GetWindowStyleFlag() const;
+    virtual long GetWindowStyleFlag() const;
+    long GetWindowStyle() const;
+    //@}
 
     /**
         Returns the value previously passed to SetWindowVariant().
@@ -1312,7 +1309,7 @@ public:
         GetEventHandler()->SafelyProcessEvent(event);
         @endcode
     */
-    bool HandleWindowEvent(wxEvent& event);
+    bool HandleWindowEvent(wxEvent& event) const;
 
     /**
         Returns @true if this window has the current mouse capture.
@@ -1358,7 +1355,7 @@ public:
         @param orient
             Orientation to check, either wxHORIZONTAL or wxVERTICAL.
     */
-    virtual bool HasScrollbar(int orient) const;
+    bool HasScrollbar(int orient) const;
 
     /**
         Returns @true if this window background is transparent (as, for example,
@@ -1368,7 +1365,7 @@ public:
         shouldn't have to call it. You may, however, have to override it in your
         wxWindow-derived class to ensure that background is painted correctly.
     */
-    virtual bool HasTransparentBackground() const;
+    virtual bool HasTransparentBackground();
 
     /**
         Equivalent to calling wxWindow::Show(@false).
@@ -1385,7 +1382,7 @@ public:
         @since 2.9.0
     */
     virtual bool HideWithEffect(wxShowEffect effect,
-                                unsigned timeout = 0);
+                                unsigned int timeout = 0);
 
     /**
         This function is (or should be, in case of custom controls) called during
@@ -1410,13 +1407,13 @@ public:
         just changing the font or colour of their common parent, hence in this case we
         do inherit the parents attributes.
     */
-    void InheritAttributes();
+    virtual void InheritAttributes();
 
     /**
         Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data
         to the dialog via validators.
     */
-    void InitDialog();
+    virtual void InitDialog();
 
     /**
         Resets the cached best size value so it will be recalculated the next time it
@@ -1443,7 +1440,7 @@ public:
 
         @see Enable()
     */
-    virtual bool IsEnabled() const;
+    bool IsEnabled() const;
 
     //@{
     /**
@@ -1452,9 +1449,9 @@ public:
         only redrawing those areas, which have been exposed.
     */
     bool IsExposed(int x, int y) const;
-    const bool IsExposed(wxPoint amp;pt) const;
-    const bool IsExposed(int x, int y, int w, int h) const;
-    const bool IsExposed(wxRect amp;rect) const;
+    bool IsExposed(wxPoint& pt) const;
+    bool IsExposed(int x, int y, int w, int h) const;
+    bool IsExposed(wxRect& rect) const;
     //@}
 
     /**
@@ -1462,7 +1459,7 @@ public:
 
         @see Freeze(), Thaw()
     */
-    virtual bool IsFrozen() const;
+    bool IsFrozen() const;
 
     /**
         Returns @true if the window is retained, @false otherwise.
@@ -1479,7 +1476,7 @@ public:
 
         @see AlwaysShowScrollbars()
     */
-    bool IsScrollbarAlwaysShown(int orient);
+    virtual bool IsScrollbarAlwaysShown(int orient) const;
 
     /**
         Returns @true if the window is shown, @false if it has been hidden.
@@ -1509,36 +1506,41 @@ public:
         dialogs are considered to be top-level windows (even if they have a parent
         window).
     */
-    bool IsTopLevel() const;
+    virtual bool IsTopLevel() const;
 
     /**
         Invokes the constraint-based layout algorithm or the sizer-based algorithm
         for this window.
 
-        See SetAutoLayout(): when auto layout is on, this function gets called automatically
-        when the window is resized.
+        This function does not get called automatically when the window is resized
+        because lots of windows deriving from wxWindow does not need this functionality.
+        If you want to have Layout() called automatically, you should derive
+        from wxPanel (see wxPanel::Layout).
 
         @see @ref overview_windowsizing
     */
-    void Layout();
+    virtual bool Layout();
 
     /**
         Lowers the window to the bottom of the window hierarchy (Z-order).
 
+        @remarks
+        This function only works for wxTopLevelWindow-derived classes.
+
         @see Raise()
     */
-    void Lower();
+    virtual void Lower();
 
     /**
         Disables all other windows in the application so that
         the user can only interact with this window.
 
-        @param flag
+        @param modal
             If @true, this call disables all other windows in the application so that
             the user can only interact with this window. If @false, the effect is
             reversed.
     */
-    virtual void MakeModal(bool flag);
+    virtual void MakeModal(bool modal = true);
 
     /**
         Moves the window to the given position.
@@ -1547,6 +1549,8 @@ public:
             Required x position.
         @param y
             Required y position.
+        @param flags
+            See SetSize() for more info about this parameter.
 
         @remarks Implementations of SetSize can also implicitly implement the
                  Move() function, which is defined in the base wxWindow class as the call:
@@ -1556,13 +1560,15 @@ public:
 
         @see SetSize()
     */
-    void Move(int x, int y);
+    void Move(int x, int y, int flags = wxSIZE_USE_EXISTING);
 
     /**
         Moves the window to the given position.
 
         @param pt
             wxPoint object representing the position.
+        @param flags
+            See SetSize() for more info about this parameter.
 
         @remarks Implementations of SetSize() can also implicitly implement the
                  Move() function, which is defined in the base wxWindow class as the call:
@@ -1572,7 +1578,7 @@ public:
 
         @see SetSize()
     */
-    void Move(const wxPoint& pt);
+    void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
 
     /**
         Moves this window in the tab navigation order after the specified @e win.
@@ -1615,13 +1621,13 @@ public:
                  control. See also wxNavigationKeyEvent and
                  HandleAsNavigationKey.
     */
-    bool Navigate(int flags = wxNavigationKeyEvent::IsForward);
+    bool Navigate(int flags = IsForward);
 
     /**
         Performs a keyboard navigation action inside this window.
         See Navigate() for more information.
     */
-    bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward);
+    bool NavigateIn(int flags = IsForward);
 
     /**
         Create a new ID or range of IDs that are not currently in use.
@@ -1684,7 +1690,7 @@ public:
         @see SetEventHandler(), GetEventHandler(),
              PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler
     */
-    wxEvtHandler* PopEventHandler(bool deleteHandler = false) const;
+    wxEvtHandler* PopEventHandler(bool deleteHandler = false);
 
     //@{
     /**
@@ -1695,14 +1701,10 @@ public:
         processed as usually. If the coordinates are not specified, current mouse
         cursor position is used.
 
-        @param menu
-            Menu to pop up.
-        @param pos
-            The position where the menu will appear.
-        @param x
-            Required x position for the menu to appear.
-        @param y
-            Required y position for the menu to appear.
+        @a menu is the menu to pop up.
+
+        The position where the menu will appear can be specified either as a
+        wxPoint @a pos or by two integers (@a x and @a y).
 
         @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
                  ensure that the menu items are in the correct state.
@@ -1758,11 +1760,13 @@ public:
 
     /**
         Raises the window to the top of the window hierarchy (Z-order).
-        In current version of wxWidgets this works both for managed and child windows.
+
+        @remarks
+        This function only works for wxTopLevelWindow-derived classes.
 
         @see Lower()
     */
-    void Raise();
+    virtual void Raise();
 
     /**
         Causes this window, and all of its children recursively (except under wxGTK1
@@ -1820,8 +1824,8 @@ public:
 
         @see UnregisterHotKey()
     */
-    bool RegisterHotKey(int hotkeyId, int modifiers,
-                        int virtualKeyCode);
+    virtual bool RegisterHotKey(int hotkeyId, int modifiers,
+                                int virtualKeyCode);
 
     /**
         Releases mouse input captured with CaptureMouse().
@@ -1829,7 +1833,7 @@ public:
         @see CaptureMouse(), HasCapture(), ReleaseMouse(),
              wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent
     */
-    virtual void ReleaseMouse();
+    void ReleaseMouse();
 
     /**
         Removes a child window.
@@ -1870,7 +1874,6 @@ public:
     */
     virtual bool Reparent(wxWindow* newParent);
 
-    //@{
     /**
         Converts from screen to client window coordinates.
 
@@ -1878,12 +1881,16 @@ public:
             Stores the screen x coordinate and receives the client x coordinate.
         @param y
             Stores the screen x coordinate and receives the client x coordinate.
+    */
+    void ScreenToClient(int* x, int* y) const;
+
+    /**
+        Converts from screen to client window coordinates.
+
         @param pt
-            The screen position for the second form of the function.
+            The screen position.
     */
-    virtual void ScreenToClient(int* x, int* y) const;
-    virtual wxPoint ScreenToClient(const wxPoint& pt) const;
-    //@}
+    wxPoint ScreenToClient(const wxPoint& pt) const;
 
     /**
         Scrolls the window by the given number of lines down (if @a lines is
@@ -1932,7 +1939,7 @@ public:
                               const wxRect* rect = NULL);
 
     /**
-        This function sends a dummy @ref overview_wxsizeevent "size event" to
+        This function sends a dummy @ref wxSizeEvent "size event" to
         the window allowing it to re-layout its children positions.
 
         It is sometimes useful to call this function after adding or deleting a
@@ -1949,7 +1956,7 @@ public:
         @param flags
             May include @c wxSEND_EVENT_POST. Default value is 0.
     */
-    void SendSizeEvent(int flags = 0);
+    virtual void SendSizeEvent(int flags = 0);
 
     /**
         Safe wrapper for GetParent()->SendSizeEvent().
@@ -1990,8 +1997,9 @@ public:
         updated when its size changes.
 
         @param autoLayout
-            Set this to @true if you wish the Layout function to be
-            called automatically when the window is resized.
+            Set this to @true if you wish the Layout() function to be
+            called automatically when the window is resized
+            (really happens only if you derive from wxPanel or wxTopLevelWindow).
 
         @see SetConstraints()
     */
@@ -2030,7 +2038,7 @@ public:
         @see SetBackgroundColour(), GetForegroundColour(),
              SetTransparent()
     */
-    virtual void SetBackgroundStyle(wxBackgroundStyle style);
+    virtual bool SetBackgroundStyle(wxBackgroundStyle style);
 
     /**
         This method is only implemented by ports which have support for
@@ -2047,7 +2055,7 @@ public:
     /**
         Sets the caret() associated with the window.
     */
-    void SetCaret(wxCaret* caret) const;
+    void SetCaret(wxCaret* caret);
 
     //@{
     /**
@@ -2057,13 +2065,6 @@ public:
         than SetSize(), since the application need not worry about what dimensions
         the border or title bar have when trying to fit the window around panel
         items, for example.
-
-        @param width
-            The required client area width.
-        @param height
-            The required client area height.
-        @param size
-            The required client size.
     */
     virtual void SetClientSize(int width, int height);
     virtual void SetClientSize(const wxSize& size);
@@ -2106,7 +2107,7 @@ public:
 
         @see ::wxSetCursor, wxCursor
     */
-    virtual void SetCursor(const wxCursor& cursor);
+    virtual bool SetCursor(const wxCursor& cursor);
 
     /**
         Associates a drop target with this window.
@@ -2114,7 +2115,7 @@ public:
 
         @see GetDropTarget(), @ref overview_dnd
     */
-    void SetDropTarget(wxDropTarget* target);
+    virtual void SetDropTarget(wxDropTarget* target);
 
     /**
         Sets the event handler for this window.
@@ -2142,7 +2143,7 @@ public:
         The currently defined extra style bits are reported in the class
         description.
     */
-    void SetExtraStyle(long exStyle);
+    virtual void SetExtraStyle(long exStyle);
 
     /**
         This sets the window to receive keyboard input.
@@ -2182,7 +2183,7 @@ public:
 
         @see GetFont(), InheritAttributes()
     */
-    bool SetFont(const wxFont& font);
+    virtual bool SetFont(const wxFont& font);
 
     /**
         Sets the foreground colour of the window.
@@ -2200,7 +2201,7 @@ public:
         @see GetForegroundColour(), SetBackgroundColour(),
              GetBackgroundColour(), ShouldInheritColours()
     */
-    virtual void SetForegroundColour(const wxColour& colour);
+    virtual bool SetForegroundColour(const wxColour& colour);
 
     /**
         Sets the help text to be used as context-sensitive help for this window.
@@ -2209,7 +2210,7 @@ public:
 
         @see GetHelpText(), wxHelpProvider::AddHelp()
     */
-    virtual void SetHelpText(const wxString& helpText);
+    void SetHelpText(const wxString& helpText);
 
     /**
         Sets the identifier of the window.
@@ -2221,13 +2222,7 @@ public:
 
         @see GetId(), @ref overview_windowids
     */
-    void SetId(int id);
-
-    /**
-        Sets the initial window size if none is given (i.e. at least one of the
-        components of the size passed to ctor/Create() is wxDefaultCoord).
-    */
-    virtual void SetInitialBestSize(const wxSize& size);
+    void SetId(wxWindowID winid);
 
     /**
         A @e smart SetSize that will fill in default size components with the
@@ -2262,7 +2257,7 @@ public:
 
         @see SetMaxSize()
     */
-    void SetMaxClientSize(const wxSize& size);
+    virtual void SetMaxClientSize(const wxSize& size);
 
     /**
         Sets the maximum size of the window, to indicate to the sizer layout mechanism
@@ -2270,7 +2265,7 @@ public:
 
         @see SetMaxClientSize()
     */
-    void SetMaxSize(const wxSize& size);
+    virtual void SetMaxSize(const wxSize& size);
 
     /**
         Sets the minimum client size of the window, to indicate to the sizer
@@ -2286,7 +2281,7 @@ public:
 
         @see SetMinSize()
     */
-    void SetMinClientSize(const wxSize& size);
+    virtual void SetMinClientSize(const wxSize& size);
 
     /**
         Sets the minimum size of the window, to indicate to the sizer layout
@@ -2302,7 +2297,7 @@ public:
 
         @see SetMinClientSize()
     */
-    void SetMinSize(const wxSize& size);
+    virtual void SetMinSize(const wxSize& size);
 
     /**
         Sets the window's name.
@@ -2341,7 +2336,7 @@ public:
     /**
         @deprecated use wxDC::SetPalette instead.
     */
-    virtual void SetPalette(wxPalette* palette);
+    void SetPalette(const wxPalette& pal);
 
     /**
         Sets the position of one of the built-in scrollbars.
@@ -2375,35 +2370,36 @@ public:
         @param thumbSize
             The size of the thumb, or visible portion of the scrollbar, in scroll units.
         @param range
-            The maximum position of the scrollbar.
+            The maximum position of the scrollbar. Value of -1 can be used to
+            ask for the scrollbar to be shown but in the disabled state: this
+            can be used to avoid removing the scrollbar even when it is not
+            needed (currently this is only implemented in wxMSW port).
         @param refresh
             @true to redraw the scrollbar, @false otherwise.
 
-        @remarks Let's say you wish to display 50 lines of text, using the same
-                 font. The window is sized so that you can only see 16
-                 lines at a time.
-                 You would use:
-                 @code
-                 SetScrollbar(wxVERTICAL, 0, 16, 50);
-                 @endcode
-                 Note that with the window at this size, the thumb position can never
-                 go above 50 minus 16, or 34. You can determine how many lines are
-                 currently visible by dividing the current view size by the character
-                 height in pixels.
-                 When defining your own scrollbar behaviour, you will always need
-                 to recalculate the scrollbar settings when the window size changes.
-                 You could therefore put your scrollbar calculations and SetScrollbar
-                 call into a function named AdjustScrollbars, which can be called
-                 initially and also from your wxSizeEvent handler function.
+        @remarks
+            Let's say you wish to display 50 lines of text, using the same font.
+            The window is sized so that you can only see 16 lines at a time.
+            You would use:
+            @code
+            SetScrollbar(wxVERTICAL, 0, 16, 50);
+            @endcode
+            Note that with the window at this size, the thumb position can never
+            go above 50 minus 16, or 34. You can determine how many lines are
+            currently visible by dividing the current view size by the character
+            height in pixels.
+            When defining your own scrollbar behaviour, you will always need
+            to recalculate the scrollbar settings when the window size changes.
+            You could therefore put your scrollbar calculations and SetScrollbar
+            call into a function named AdjustScrollbars, which can be called
+            initially and also from your wxSizeEvent handler function.
 
         @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
     */
     virtual void SetScrollbar(int orientation, int position,
-                              int thumbSize,
-                              int range,
+                              int thumbSize, int range,
                               bool refresh = true);
 
-    //@{
     /**
         Sets the size of the window in pixels.
 
@@ -2419,10 +2415,6 @@ public:
         @param height
             Required height position in pixels, or wxDefaultCoord to indicate that the
             existing value should be used.
-        @param size
-            wxSize object for setting the size.
-        @param rect
-            wxRect object for setting the position and size.
         @param sizeFlags
             Indicates the interpretation of other parameters.
             It is a bit list of the following:
@@ -2444,23 +2436,41 @@ public:
                                later and only implemented for MSW and ignored elsewhere
                                currently).
 
-        @remarks The second form is a convenience for calling the first form with
-                 default x and y parameters, and must be used with
-                 non-default width and height values.
-                 The first form sets the position and optionally size, of the window.
+        @remarks This overload sets the position and optionally size, of the window.
                  Parameters may be wxDefaultCoord to indicate either that a default
                  should be supplied by wxWidgets, or that the current value of the
                  dimension should be used.
 
         @see Move()
     */
-    virtual void SetSize(int x, int y, int width, int height,
-                         int sizeFlags = wxSIZE_AUTO);
+    void SetSize(int x, int y, int width, int height,
+                 int sizeFlags = wxSIZE_AUTO);
+
+    //@{
+    /**
+        Sets the size of the window in pixels.
+        The size is specified using a wxRect, wxSize or by a couple of @c int objects.
+
+        @remarks This form must be used with non-default width and height values.
+
+        @see Move()
+    */
     virtual void SetSize(const wxRect& rect);
-    virtual void SetSize(int width, int height);
     virtual void SetSize(const wxSize& size);
+    virtual void SetSize(int width, int height);
     //@}
 
+    /**
+        Use of this function for windows which are not toplevel windows
+        (such as wxDialog or wxFrame) is discouraged.
+        Please use SetMinSize() and SetMaxSize() instead.
+
+        @see wxTopLevelWindow::SetSizeHints
+    */
+    void SetSizeHints( const wxSize& minSize,
+                       const wxSize& maxSize=wxDefaultSize,
+                       const wxSize& incSize=wxDefaultSize);
+
     /**
         Sets the window to have the given layout sizer.
         The window will then own the object, and will take care of its deletion.
@@ -2529,7 +2539,7 @@ public:
         fully transparent window and 255 to the fully opaque one. The constants
         @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used.
     */
-    bool SetTransparent(wxByte alpha);
+    virtual bool SetTransparent(wxByte alpha);
 
     /**
         Deletes the current validator (if any) and sets the window validator, having
@@ -2545,11 +2555,7 @@ public:
     void SetVirtualSize(const wxSize& size);
     //@}
 
-    /**
-        Identical to SetWindowStyleFlag().
-    */
-    void SetWindowStyle(long style);
-
+    //@{
     /**
         Sets the style of the window. Please note that some styles cannot be changed
         after the window creation and that Refresh() might need to be be called
@@ -2560,6 +2566,8 @@ public:
         @see GetWindowStyleFlag()
     */
     virtual void SetWindowStyleFlag(long style);
+    void SetWindowStyle(long style);
+    //@}
 
     /**
         This function can be called under all platforms but only does anything under
@@ -2578,7 +2586,7 @@ public:
         The base class version returns @false, but this method is overridden in
         wxControl where it returns @true.
     */
-    virtual bool ShouldInheritColours();
+    virtual bool ShouldInheritColours() const;
 
     /**
         Shows or hides the window. You may need to call Raise()
@@ -2615,7 +2623,7 @@ public:
         @see HideWithEffect()
     */
     virtual bool ShowWithEffect(wxShowEffect effect,
-                                unsigned timeout = 0);
+                                unsigned int timeout = 0);
 
     /**
         Reenables window updating after a previous call to Freeze().
@@ -2627,7 +2635,7 @@ public:
 
         @see wxWindowUpdateLocker, Freeze(), IsFrozen()
     */
-    virtual void Thaw();
+    void Thaw();
 
     /**
         Turns the given @a flag on if it's currently turned off and vice versa.
@@ -2682,7 +2690,7 @@ public:
 
         @see RegisterHotKey()
     */
-    bool UnregisterHotKey(int hotkeyId);
+    virtual bool UnregisterHotKey(int hotkeyId);
 
     /**
         Unreserve an ID or range of IDs that was reserved by NewControlId().
@@ -2774,7 +2782,39 @@ public:
         @param y
             The new y position for the cursor.
     */
-    void WarpPointer(int x, int y);
+    virtual void WarpPointer(int x, int y);
+
+
+protected:
+
+    /**
+        Gets the size which best suits the window: for a control, it would be
+        the minimal size which doesn't truncate the control, for a panel - the
+        same size as it would have after a call to Fit().
+
+        The default implementation of this function is designed for use in container
+        windows, such as wxPanel, and works something like this:
+        -# If the window has a sizer then it is used to calculate the best size.
+        -# Otherwise if the window has layout constraints then those are used to
+           calculate the best size.
+        -# Otherwise if the window has children then the best size is set to be large
+           enough to show all the children.
+        -# Otherwise if there are no children then the window's minimal size will be
+           used as its best size.
+        -# Otherwise if there is no minimal size set, then the current size is used
+           for the best size.
+
+        @see @ref overview_windowsizing
+    */
+    virtual wxSize DoGetBestSize() const;
+
+
+    /**
+        Sets the initial window size if none is given (i.e. at least one of the
+        components of the size passed to ctor/Create() is wxDefaultCoord).
+        @deprecated @todo provide deprecation description
+    */
+    virtual void SetInitialBestSize(const wxSize& size);
 };
 
 
@@ -2783,7 +2823,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
 //@{
 
 /**