]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/window.h
Ticket #9592: gtk-choice-setcolumns.2.diff
[wxWidgets.git] / interface / window.h
index 8b2f9d40973436964e555abfaca021353f6dbdb6..30102c6bab213fa57934c378f0f0792e36a20673 100644 (file)
     Please note that all children of the window will be deleted automatically by
     the destructor before the window itself is deleted which means that you don't
     have to worry about deleting them manually. Please see the @ref
-    overview_windowdeletionoverview "window
-    deletion overview" for more information.
+    overview_windowdeletion "window deletion overview" for more information.
 
     Also note that in this, and many others, wxWidgets classes some
     @c GetXXX() methods may be overloaded (as, for example,
-    wxWindow::GetSize or
-    wxWindow::GetClientSize). In this case, the overloads
+    wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads
     are non-virtual because having multiple virtual functions with the same name
     results in a virtual function name hiding at the derived class level (in
     English, this means that the derived class has to override all overloaded
     changes the behaviour of the latter.
 
     @beginStyleTable
-    @style{wxBORDER_DEFAULT}:
+    @style{wxBORDER_DEFAULT}
            The window class will decide the kind of border to show, if any.
-    @style{wxBORDER_SIMPLE}:
+    @style{wxBORDER_SIMPLE}
            Displays a thin border around the window. wxSIMPLE_BORDER is the
            old name for this style.
-    @style{wxBORDER_SUNKEN}:
+    @style{wxBORDER_SUNKEN}
            Displays a sunken border. wxSUNKEN_BORDER is the old name for this
            style.
-    @style{wxBORDER_RAISED}:
+    @style{wxBORDER_RAISED}
            Displays a raised border. wxRAISED_BORDER is the old name for this
            style.
-    @style{wxBORDER_STATIC}:
+    @style{wxBORDER_STATIC}
            Displays a border suitable for a static control.  wxSTATIC_BORDER
            is the old name for this style. Windows only.
-    @style{wxBORDER_THEME}:
+    @style{wxBORDER_THEME}
            Displays a native border suitable for a control, on the current
            platform. On Windows XP or Vista, this will be a themed border; on
            most other platforms a sunken border will be used. For more
            information for themed borders on Windows, please see Themed
            borders on Windows.
-    @style{wxBORDER_NONE}:
+    @style{wxBORDER_NONE}
            Displays no border, overriding the default border style for the
            window. wxNO_BORDER is the old name for this style.
-    @style{wxBORDER_DOUBLE}:
+    @style{wxBORDER_DOUBLE}
            This style is obsolete and should not be used.
-    @style{wxTRANSPARENT_WINDOW}:
+    @style{wxTRANSPARENT_WINDOW}
            The window is transparent, that is, it will not receive paint
            events. Windows only.
-    @style{wxTAB_TRAVERSAL}:
+    @style{wxTAB_TRAVERSAL}
            Use this to enable tab traversal for non-dialog windows.
-    @style{wxWANTS_CHARS}:
+    @style{wxWANTS_CHARS}
            Use this to indicate that the window wants to get all char/key
            events for all keys - even for keys like TAB or ENTER which are
            usually used for dialog navigation and which wouldn't be generated
            the arrows or etc., but would still like to have normal keyboard
            navigation take place, you should call Navigate in response to the
            key events for Tab and Shift-Tab.
-    @style{wxNO_FULL_REPAINT_ON_RESIZE}:
+    @style{wxNO_FULL_REPAINT_ON_RESIZE}
            On Windows, this style used to disable repainting the window
            completely when its size is changed. Since this behaviour is now
            the default, the style is now obsolete and no longer has an effect.
-    @style{wxVSCROLL}:
+    @style{wxVSCROLL}
            Use this style to enable a vertical scrollbar. Notice that this
            style cannot be used with native controls which don't support
            scrollbars nor with top-level windows in most ports.
-    @style{wxHSCROLL}:
+    @style{wxHSCROLL}
            Use this style to enable a horizontal scrollbar. The same
            limitations as for wxVSCROLL apply to this style.
-    @style{wxALWAYS_SHOW_SB}:
+    @style{wxALWAYS_SHOW_SB}
            If a window has scrollbars, disable them instead of hiding them
            when they are not needed (i.e. when the size of the window is big
            enough to not require the scrollbars to navigate it). This style is
            currently implemented for wxMSW, wxGTK and wxUniversal and does
            nothing on the other platforms.
-    @style{wxCLIP_CHILDREN}:
+    @style{wxCLIP_CHILDREN}
            Use this style to eliminate flicker caused by the background being
            repainted, then children being painted over them. Windows only.
-    @style{wxFULL_REPAINT_ON_RESIZE}:
+    @style{wxFULL_REPAINT_ON_RESIZE}
            Use this style to force a complete redraw of the window whenever it
            is resized instead of redrawing just the part of the window
            affected by resizing. Note that this was the behaviour by default
     @endStyleTable
 
     @beginExtraStyleTable
-    @style{wxWS_EX_VALIDATE_RECURSIVELY}:
+    @style{wxWS_EX_VALIDATE_RECURSIVELY}
            By default, Validate/TransferDataTo/FromWindow() only work on
            direct children of the window (compatible behaviour). Set this flag
            to make them recursively descend into all subwindows.
-    @style{wxWS_EX_BLOCK_EVENTS}:
+    @style{wxWS_EX_BLOCK_EVENTS}
            wxCommandEvents and the objects of the derived classes are
            forwarded to the parent window and so on recursively by default.
            Using this flag for the given window allows to block this
            propagation at this window, i.e. prevent the events from being
            propagated further upwards. Dialogs have this flag on by default.
-    @style{wxWS_EX_TRANSIENT}:
+    @style{wxWS_EX_TRANSIENT}
            Don't use this window as an implicit parent for the other windows:
            this must be used with transient windows as otherwise there is the
            risk of creating a dialog/frame with this window as a parent which
            would lead to a crash if the parent is destroyed before the child.
-    @style{wxWS_EX_PROCESS_IDLE}:
+    @style{wxWS_EX_PROCESS_IDLE}
            This window should always process idle events, even if the mode set
            by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.
-    @style{wxWS_EX_PROCESS_UI_UPDATES}:
+    @style{wxWS_EX_PROCESS_UI_UPDATES}
            This window should always process UI update events, even if the
            mode set by wxUpdateUIEvent::SetMode is
            wxUPDATE_UI_PROCESS_SPECIFIED.
     @library{wxcore}
     @category{FIXME}
 
-    @see @ref overview_eventhandlingoverview, @ref overview_windowsizingoverview
-    "Window sizing overview"
+    @see @ref overview_eventhandling "Event handling overview", 
+         @ref overview_windowsizing "Window sizing overview"
 */
 class wxWindow : public wxEvtHandler
 {
 public:
-    //@{
+    /**
+       Default constructor
+    */
+    wxWindow();
+    
     /**
         Constructs a window, which can be a child of a frame, dialog or any other
         non-control window.
@@ -161,13 +163,11 @@ public:
         @param name
             Window name.
     */
-    wxWindow();
     wxWindow(wxWindow* parent, wxWindowID id,
              const wxPoint& pos = wxDefaultPosition,
              const wxSize& size = wxDefaultSize,
              long style = 0,
              const wxString& name = wxPanelNameStr);
-    //@}
 
     /**
         Destructor. Deletes all sub-windows, then deletes itself. Instead of using
@@ -175,7 +175,7 @@ public:
         use Destroy() so that wxWidgets
         can delete a window only when it is safe to do so, in idle time.
 
-        @see @ref overview_windowdeletionoverview "Window deletion overview",
+        @see @ref overview_windowdeletion "Window Deletion Overview",
              Destroy(), wxCloseEvent
     */
     ~wxWindow();
@@ -187,7 +187,7 @@ public:
 
         @see AcceptsFocusFromKeyboard()
     */
-    bool AcceptsFocus() const;
+    virtual bool AcceptsFocus() const;
 
     /**
         This method may be overridden in the derived classes to return @false to
@@ -195,8 +195,15 @@ public:
         clicks it with the mouse, it shouldn't be included in the TAB traversal chain
         when using the keyboard.
     */
-    bool AcceptsFocusFromKeyboard() const;
+    virtual bool AcceptsFocusFromKeyboard() const;
 
+     /**
+        Overridden to indicate wehter this window or one of its children accepts
+        focus. Usually it's the same as AcceptsFocus() but is overridden for
+        container windows
+     */
+    virtual bool AcceptsFocusRecursively() const;
+    
     /**
         Adds a child window.  This is called automatically by window creation
         functions so should not be required by the application programmer.
@@ -212,7 +219,7 @@ public:
         Call this function to force one or both scrollbars to be always shown, even if
         the window is big enough to show its entire contents without scrolling.
 
-        @wxsince{2.9.0}
+        @since 2.9.0
 
         @param hflag
             Whether the horizontal scroll bar should always be visible.
@@ -319,8 +326,8 @@ public:
         @param pt
             The client position for the second form of the function.
     */
-    virtual void ClientToScreen(int* x, int* y) const;
-    const virtual wxPoint  ClientToScreen(const wxPoint& pt) const;
+    void ClientToScreen(int* x, int* y) const;
+    wxPoint ClientToScreen(const wxPoint& pt) const;
     //@}
 
     /**
@@ -369,7 +376,7 @@ public:
                  windows (wxFrame and wxDialog classes) as the others
                  are not supposed to have any special OnClose() logic.
 
-        @see @ref overview_windowdeletionoverview "Window deletion overview",
+        @see @ref overview_windowdeletion "Window Deletion Overview",
              Destroy(), wxCloseEvent
     */
     bool Close(bool force = false);
@@ -422,7 +429,7 @@ public:
         non-existent
         windows.
 
-        @returns @true if the window has either been successfully deleted, or it
+        @return @true if the window has either been successfully deleted, or it
                  has been added to the list of windows pending real
                  deletion.
     */
@@ -434,9 +441,9 @@ public:
     virtual void DestroyChildren();
 
     /**
-        Disables the window, same as @ref enable() Enable(@false).
+        Disables the window. Same as @ref Enable() Enable(@false).
 
-        @returns Returns @true if the window has been disabled, @false if it had
+        @return Returns @true if the window has been disabled, @false if it had
                  been already disabled before the call to this function.
     */
     bool Disable();
@@ -445,16 +452,27 @@ public:
         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 values in the wxUpdateUIEvent and
-        act appropriately. For example, to allow frame and dialog title updating,
-        wxWidgets
-        implements this function as follows:
+        This function is called by UpdateWindowUI() in order to check return
+        values in the wxUpdateUIEvent and act appropriately.
     */
     virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
 
@@ -477,7 +495,7 @@ public:
         @param enable
             If @true, enables the window for input. If @false, disables the window.
 
-        @returns Returns @true if the window has been enabled or disabled, @false
+        @return Returns @true if the window has been enabled or disabled, @false
                  if nothing was done, i.e. if the window had already
                  been in the specified state.
 
@@ -495,13 +513,18 @@ public:
     */
     static wxWindow* FindFocus();
 
-    //@{
     /**
-        Find a child of this window, by name.
+        Find a child of this window, by @a id. May return @a this if
+        it matches itself.
     */
     wxWindow* FindWindow(long id) const;
-    const wxWindow*  FindWindow(const wxString& name) const;
-    //@}
+    
+
+    /**
+        Find a child of this window, by name. May return @a this if
+        it matches itself.
+    */
+    wxWindow* FindWindow(const wxString& name) const;
 
     /**
         Find the first window with the given @e id.
@@ -544,13 +567,22 @@ public:
                                       wxWindow* parent = NULL);
 
     /**
-        Sizes the window so that it fits around its subwindows. This function won't do
-        anything if there are no subwindows and will only really work correctly if
-        sizers are used for the subwindows layout. Also, if the window has exactly one
-        subwindow it is better (faster and the result is more precise as Fit adds some
-        margin to account for fuzziness of its calculations) to call
+        Sizes the window so that it fits around its subwindows.
 
-        instead of calling Fit.
+        This function won't do anything if there are no subwindows and will only really
+        work correctly if sizers are used for the subwindows layout.
+
+        Also, if the window has exactly one subwindow it is better (faster and the result
+        is more precise as Fit() adds some margin to account for fuzziness of its calculations)
+        to call:
+
+        @code
+            window->SetClientSize(child->GetSize());
+        @endcode
+
+        instead of calling Fit().
+
+        @see @ref overview_windowsizing
     */
     virtual void Fit();
 
@@ -596,8 +628,7 @@ public:
     wxAccessible* GetAccessible();
 
     /**
-        This method is deprecated, use GetEffectiveMinSize()
-        instead.
+        This method is deprecated, use GetEffectiveMinSize() instead.
     */
     wxSize GetAdjustedBestSize() const;
 
@@ -607,7 +638,7 @@ public:
         @see SetBackgroundColour(), SetForegroundColour(),
              GetForegroundColour()
     */
-    virtual wxColour GetBackgroundColour() const;
+    wxColour GetBackgroundColour() const;
 
     /**
         Returns the background style of the window. The background style can be one of:
@@ -680,11 +711,10 @@ public:
     //@{
     /**
         Returns a reference to the list of the window's children. @c wxWindowList
-        is a type-safe wxList-like class whose elements are of type
-        @c wxWindow *.
+        is a type-safe wxList-like class whose elements are of type @c wxWindow*.
     */
-    wxWindowList GetChildren() const;
-    const wxWindowList GetChildren() const;
+    wxWindowList& GetChildren();
+    const wxWindowList& GetChildren() const;
     //@}
 
     /**
@@ -697,7 +727,7 @@ public:
         ignore under other platforms. Under Mac, it will change the size of the
         returned font. See SetWindowVariant()
         for more about this.
-        This static method is "overridden'' in many derived classes and so calling,
+        This static method is "overridden" in many derived classes and so calling,
         for example, wxButton::GetClassDefaultAttributes() will typically
         return the values appropriate for a button which will be normally different
         from those returned by, say, wxListCtrl::GetClassDefaultAttributes().
@@ -727,7 +757,7 @@ public:
         @see GetSize(), GetVirtualSize()
     */
     void GetClientSize(int* width, int* height) const;
-    const wxSize  GetClientSize() const;
+    wxSize GetClientSize() const;
     //@}
 
     /**
@@ -739,14 +769,14 @@ public:
         Return the sizer that this window is a member of, if any, otherwise
         @NULL.
     */
-    const wxSizer* GetContainingSizer() const;
+    wxSizer* GetContainingSizer() const;
 
     /**
         Return the cursor associated with this window.
 
         @see SetCursor()
     */
-    const wxCursor GetCursor() const;
+    const wxCursor& GetCursor() const;
 
     /**
         Currently this is the same as calling
@@ -755,7 +785,7 @@ public:
         the call is automatically dispatched to the correct class (as usual with
         virtual functions) and you don't have to specify the class name explicitly.
         The other one is that in the future this function could return different
-        results, for example it might return a different font for an "Ok'' button
+        results, for example it might return a different font for an "Ok" button
         than for a generic button if the users GUI is configured to show such buttons
         in bold font. Of course, the down side is that it is impossible to call this
         function without actually having an object to apply it to whereas the static
@@ -766,16 +796,16 @@ public:
     /**
         Returns the associated drop target, which may be @NULL.
 
-        @see SetDropTarget(), @ref overview_wxdndoverview
+        @see SetDropTarget(), @ref overview_dnd
     */
     wxDropTarget* GetDropTarget() const;
 
     /**
-        Merges the window's best size into the min size and returns the
-        result.  This is the value used by sizers to determine the appropriate
+        Merges the window's best size into the min size and returns the result.
+        This is the value used by sizers to determine the appropriate
         ammount of space to allocate for the widget.
 
-        @see GetBestSize(), SetInitialSize()
+        @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
     */
     wxSize GetEffectiveMinSize() const;
 
@@ -811,7 +841,7 @@ public:
         @see SetForegroundColour(), SetBackgroundColour(),
              GetBackgroundColour()
     */
-    virtual wxColour GetForegroundColour();
+    wxColour GetForegroundColour();
 
     /**
         Returns the grandparent of a window, or @NULL if there isn't one.
@@ -905,10 +935,10 @@ public:
 
     /**
         Returns the minimum size of the window, an indication to the sizer layout
-        mechanism
-        that this is the minimum required size. It normally just returns the value set
-        by SetMinSize(), but it can be overridden to do the
-        calculation on demand.
+        mechanism that this is the minimum required size.
+
+        This method normally just returns the value set by SetMinSize(), but it
+        can be overridden to do the calculation on demand.
 
         @see GetMinClientSize()
     */
@@ -929,7 +959,7 @@ public:
         Returns the next window after this one among the parent children or @NULL if
         this window is the last child.
 
-        @wxsince{2.8.8}
+        @since 2.8.8
 
         @see GetPrevSibling()
     */
@@ -956,7 +986,7 @@ public:
         @param y
             The vertical position of the menu
 
-        @returns The selected menu item id or wxID_NONE if none selected or an
+        @return The selected menu item id or wxID_NONE if none selected or an
                  error occurred.
     */
     int GetPopupMenuSelectionFromUser(wxMenu& menu,
@@ -977,8 +1007,8 @@ public:
 
         @see GetScreenPosition()
     */
-    virtual void GetPosition(int* x, int* y) const;
-    const wxPoint  GetPosition() const;
+    void GetPosition(int* x, int* y) const;
+    wxPoint GetPosition() const;
     //@}
 
     /**
@@ -986,7 +1016,7 @@ public:
         @NULL if
         this window is the first child.
 
-        @wxsince{2.8.8}
+        @since 2.8.8
 
         @see GetNextSibling()
     */
@@ -997,7 +1027,7 @@ public:
 
         @see GetScreenRect()
     */
-    virtual wxRect GetRect() const;
+    wxRect GetRect() const;
 
     //@{
     /**
@@ -1011,8 +1041,8 @@ public:
 
         @see GetPosition()
     */
-    virtual void GetScreenPosition(int* x, int* y) const;
-    const wxPoint  GetScreenPosition() const;
+    void GetScreenPosition(int* x, int* y) const;
+    wxPoint GetScreenPosition() const;
     //@}
 
     /**
@@ -1021,7 +1051,7 @@ public:
 
         @see GetRect()
     */
-    virtual wxRect GetScreenRect() const;
+    wxRect GetScreenRect() const;
 
     /**
         Returns the built-in scrollbar position.
@@ -1158,7 +1188,7 @@ public:
         Navigate() if the key event is one normally used for
         keyboard navigation and return @true in this case.
 
-        @returns Returns @true if the key pressed was for navigation and was
+        @return Returns @true if the key pressed was for navigation and was
                  handled, @false otherwise.
 
         @see Navigate()
@@ -1233,24 +1263,23 @@ public:
     bool Hide();
 
     /**
-        This function hides a window, like Hide(), but using a
-        special visual effect if possible.
-        The parameters of this function are the same as for
-        ShowWithEffect(), please see their
-        description there.
+        This function hides a window, like Hide(), but using a special visual
+        effect if possible.
+
+        The parameters of this function are the same as for ShowWithEffect(),
+        please see their description there.
 
-        @wxsince{2.9.0}
+        @since 2.9.0
     */
     virtual bool HideWithEffect(wxShowEffect effect,
-                                unsigned timeout = 0,
-                                wxDirection dir = wxBOTTOM);
+                                unsigned timeout = 0);
 
     /**
         This function is (or should be, in case of custom controls) called during
         window creation to intelligently set up the window visual attributes, that is
         the font and the foreground and background colours.
-        By "intelligently'' the following is meant: by default, all windows use their
-        own @ref getclassdefaultattributes() default attributes. However
+        By "intelligently" the following is meant: by default, all windows use their
+        own @ref GetClassDefaultAttributes() default attributes. However
         if some of the parents attributes are explicitly (that is, using
         SetFont() and not
         wxWindow::SetOwnFont) changed and if the
@@ -1359,7 +1388,7 @@ public:
     /**
         Returns @true if this window is intrinsically enabled, @false otherwise,
         i.e.
-        if @ref enable() Enable(@false) had been called. This method is
+        if @ref Enable() Enable(@false) had been called. This method is
         mostly used for wxWidgets itself, user code should normally use
         IsEnabled() instead.
     */
@@ -1375,9 +1404,11 @@ public:
     /**
         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.
+
+        See SetAutoLayout(): when auto layout is on, this function gets called automatically
+        when the window is resized.
+
+        @see @ref overview_windowsizing
     */
     void Layout();
 
@@ -1450,7 +1481,7 @@ public:
             A combination of wxNavigationKeyEvent::IsForward and
         wxNavigationKeyEvent::WinChange.
 
-        @returns Returns @true if the focus was moved to another window or @false
+        @return Returns @true if the focus was moved to another window or @false
                  if nothing changed.
 
         @remarks You may wish to call this from a text control custom keypress
@@ -1473,16 +1504,16 @@ public:
         Create a new ID or range of IDs that are not currently in use.  The
         IDs will be reserved until assigned to a wxWindowIDRef()
         or unreserved with UnreserveControlId().
-        See @ref overview_windowidsoverview "Window IDs overview" for more information.
+        See @ref overview_windowids "Window IDs Overview" for more information.
 
         @param count
             The number of sequential IDs to reserve.
 
-        @returns Returns the ID or the first ID of the range, or wxID_NONE if the
+        @return Returns the ID or the first ID of the range, or wxID_NONE if the
                  specified number of identifiers couldn't be allocated.
 
-        @see UnreserveControlId(), wxIdManager, @ref overview_windowidsoverview
-             "Window IDs overview"
+        @see UnreserveControlId(), wxIdManager, @ref overview_windowids
+             "Window IDs Overview"
     */
     static wxWindowID NewControlId(int count = 1);
 
@@ -1633,7 +1664,7 @@ public:
         @param virtualKeyCode
             The virtual key code of the hotkey.
 
-        @returns @true if the hotkey was registered successfully. @false if some
+        @return @true if the hotkey was registered successfully. @false if some
                  other application already registered a hotkey with this
                  modifier/virtualKeyCode combination.
 
@@ -1674,7 +1705,7 @@ public:
             The event handler to remove, must be non-@NULL and
             must be present in this windows event handlers chain
 
-        @returns Returns @true if it was found and @false otherwise (this also
+        @return Returns @true if it was found and @false otherwise (this also
                  results in an assert failure so this function should
                  only be called when the handler is supposed to be
                  there).
@@ -1712,12 +1743,12 @@ public:
         Scrolls the window by the given number of lines down (if @a lines is
         positive) or up.
 
-        @returns Returns @true if the window was scrolled, @false if it was already
+        @return Returns @true if the window was scrolled, @false if it was already
                  on top/bottom and nothing was done.
 
         @remarks This function is currently only implemented under MSW and
-                 wxTextCtrl under wxGTK (it also works for
-                 wxScrolledWindow derived classes under all platforms).
+                 wxTextCtrl under wxGTK (it also works for wxScrolled classes
+                 under all platforms).
 
         @see ScrollPages()
     */
@@ -1727,7 +1758,7 @@ public:
         Scrolls the window by the given number of pages down (if @a pages is
         positive) or up.
 
-        @returns Returns @true if the window was scrolled, @false if it was already
+        @return Returns @true if the window was scrolled, @false if it was already
                  on top/bottom and nothing was done.
 
         @remarks This function is currently only implemented under MSW and wxGTK.
@@ -1748,8 +1779,8 @@ public:
             scrolled (this is always the case under wxGTK which doesn't support this
             parameter)
 
-        @remarks Note that you can often use wxScrolledWindow instead of using
-                 this function directly.
+        @remarks Note that you can often use wxScrolled instead of using this
+                 function directly.
     */
     virtual void ScrollWindow(int dx, int dy,
                               const wxRect* rect = NULL);
@@ -1896,7 +1927,7 @@ public:
         Associates a drop target with this window.
         If the window already has a drop target, it is deleted.
 
-        @see GetDropTarget(), @ref overview_wxdndoverview
+        @see GetDropTarget(), @ref overview_dnd
     */
     void SetDropTarget(wxDropTarget* target);
 
@@ -1935,7 +1966,7 @@ public:
         for them is found. Using this style allows to prevent them from being
         propagated beyond this window. Notice that wxDialog has this style on by
         default for the reasons explained in the
-        @ref overview_eventprocessing "event processing overview".
+        @ref overview_eventhandling "Event Handling Overview".
 
         @b wxWS_EX_TRANSIENT
 
@@ -1998,7 +2029,7 @@ public:
             Font to associate with this window, pass
             wxNullFont to reset to the default font.
 
-        @returns @true if the want was really changed, @false if it was already set
+        @return @true if the want was really changed, @false if it was already set
                  to this  font and so nothing was done.
 
         @see GetFont(), InheritAttributes()
@@ -2055,15 +2086,18 @@ public:
 
     /**
         A @e smart SetSize that will fill in default size components with the
-        window's @e best size values.  Also sets the window's minsize to
-        the value passed in for use with sizers.  This means that if a full or
-        partial size is passed to this function then the sizers will use that
-        size instead of the results of GetBestSize to determine the minimum
-        needs of the window for layout.
+        window's @e best size values.
+
+        Also sets the window's minsize to the value passed in for use with sizers.
+        This means that if a full or partial size is passed to this function then
+        the sizers will use that size instead of the results of GetBestSize() to
+        determine the minimum needs of the window for layout.
+
         Most controls will use this to set their initial size, and their min
         size to the passed in value (if any.)
 
-        @see SetSize(), GetBestSize(), GetEffectiveMinSize()
+        @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
+             @ref overview_windowsizing
     */
     void SetInitialSize(const wxSize& size = wxDefaultSize);
 
@@ -2096,18 +2130,30 @@ public:
     /**
         Sets the minimum client size of the window, to indicate to the sizer
         layout mechanism that this is the minimum required size of window's client
-        area. You may need to call this if you change the window size after
+        area.
+
+        You may need to call this if you change the window size after
         construction and before adding to its parent sizer.
 
+        Note, that just as with SetMinSize(), calling this method doesn't
+        prevent the program from explicitly making the window smaller than the
+        specified size.
+
         @see SetMinSize()
     */
     void SetMinClientSize(const wxSize& size);
 
     /**
-        Sets the minimum size of the window, to indicate to the sizer layout mechanism
-        that this is the minimum required size. You may need to call this
-        if you change the window size after construction and before adding
-        to its parent sizer.
+        Sets the minimum size of the window, to indicate to the sizer layout
+        mechanism that this is the minimum required size.
+
+        You may need to call this if you change the window size after
+        construction and before adding to its parent sizer.
+
+        Notice that calling this method doesn't prevent the program from making
+        the window explicitly smaller than the specified size by calling
+        SetSize(), it just ensures that it won't become smaller than this size
+        during the automatic layout.
 
         @see SetMinClientSize()
     */
@@ -2167,8 +2213,8 @@ public:
                  window: it is up to the application to take note of
                  scrollbar attributes and redraw contents accordingly.
 
-        @see SetScrollbar(), GetScrollPos(), GetScrollThumb(),
-             wxScrollBar, wxScrolledWindow
+        @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar,
+             wxScrolled
     */
     virtual void SetScrollPos(int orientation, int pos,
                               bool refresh = true);
@@ -2192,8 +2238,7 @@ public:
                  font. The window is sized so that you can only see 16
                  lines at a time.
 
-        @see @ref overview_scrollingoverview "Scrolling overview", wxScrollBar,
-             wxScrolledWindow, wxScrollWinEvent
+        @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent
     */
     virtual void SetScrollbar(int orientation, int position,
                               int thumbSize,
@@ -2261,16 +2306,6 @@ public:
     virtual void SetSize(const wxSize& size);
     //@}
 
-    /**
-        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.
-    */
-
-
     /**
         Sets the window to have the given layout sizer. The window
         will then own the object, and will take care of its deletion.
@@ -2282,13 +2317,11 @@ public:
 
         @param sizer
             The sizer to set. Pass @NULL to disassociate and conditionally delete
-            the window's sizer.  See below.
+            the window's sizer. See below.
         @param deleteOld
             If @true (the default), this will delete any pre-existing sizer.
             Pass @false if you wish to handle deleting the old sizer yourself.
-
-        @remarks SetSizer now enables and disables Layout automatically, but
-                 prior to wxWidgets 2.3.3 the following applied:
+        @remarks SetSizer enables and disables Layout automatically.
     */
     void SetSizer(wxSizer* sizer, bool deleteOld = true);
 
@@ -2349,34 +2382,6 @@ public:
     void SetVirtualSize(const wxSize& size);
     //@}
 
-    //@{
-    /**
-        Allows specification of minimum and maximum virtual window sizes.
-        If a pair of values is not set (or set to -1), the default values
-        will be used.
-
-        @param minW
-            Specifies the minimum width allowable.
-        @param minH
-            Specifies the minimum height allowable.
-        @param maxW
-            Specifies the maximum width allowable.
-        @param maxH
-            Specifies the maximum height allowable.
-        @param minSize
-            Minimum size.
-        @param maxSize
-            Maximum size.
-
-        @remarks If this function is called, the user will not be able to size
-                 the virtual area of the window outside the given bounds.
-    */
-    virtual void SetVirtualSizeHints(int minW, int minH, int maxW = -1,
-                                     int maxH = -1);
-    void SetVirtualSizeHints(const wxSize& minSize = wxDefaultSize,
-                             const wxSize& maxSize = wxDefaultSize);
-    //@}
-
     /**
         Identical to SetWindowStyleFlag().
     */
@@ -2421,7 +2426,7 @@ public:
         @param show
             If @true displays the window. Otherwise, hides it.
 
-        @returns @true if the window has been shown or hidden or @false if nothing
+        @return @true if the window has been shown or hidden or @false if nothing
                  was done because it already was in the requested state.
 
         @see IsShown(), Hide(), wxRadioBox::Show
@@ -2429,42 +2434,26 @@ public:
     virtual bool Show(bool show = true);
 
     /**
-        This function shows a window, like Show(), but using a
-        special visual effect if possible.
-        Possible values for @a effect are:
-
-        wxSHOW_EFFECT_ROLL
-
-        Roll window effect
-
-        wxSHOW_EFFECT_SLIDE
-
-        Sliding window effect
+        This function shows a window, like Show(), but using a special visual
+        effect if possible.
 
-        wxSHOW_EFFECT_BLEND
+        @param effect
+            The effect to use.
 
-        Fade in or out effect
+        @param timeout
+            The @a timeout parameter specifies the time of the animation, in
+            milliseconds. If the default value of 0 is used, the default
+            animation time for the current platform is used.
 
-        wxSHOW_EFFECT_EXPAND
+        @note Currently this function is only implemented in wxMSW and does the
+              same thing as Show() in the other ports.
 
-        Expanding or collapsing effect
-
-        For the roll and slide effects the @a dir parameter specifies the animation
-        direction: it can be one of @c wxTOP, @c wxBOTTOM, @c wxLEFT
-        or @c wxRIGHT. For the other effects, this parameter is unused.
-        The @a timeout parameter specifies the time of the animation, in
-        milliseconds. If the default value of 0 is used, the default animation time
-        for the current platform is used.
-        Currently this function is only implemented in wxMSW and does the same thing as
-        Show() in the other ports.
-
-        @wxsince{2.9.0}
+        @since 2.9.0
 
         @see HideWithEffect()
     */
     virtual bool ShowWithEffect(wxShowEffect effect,
-                                unsigned timeout = 0,
-                                wxDirection dir = wxBOTTOM);
+                                unsigned timeout = 0);
 
     /**
         Reenables window updating after a previous call to Freeze().
@@ -2485,7 +2474,7 @@ public:
         Also, please notice that not all styles can be changed after the control
         creation.
 
-        @returns Returns @true if the style was turned on by this function, @false
+        @return Returns @true if the style was turned on by this function, @false
                  if it was switched off.
 
         @see SetWindowStyleFlag(), HasFlag()
@@ -2509,7 +2498,7 @@ public:
         If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
         the method will also call TransferDataToWindow() of all child windows.
 
-        @returns Returns @false if a transfer failed.
+        @return Returns @false if a transfer failed.
 
         @see TransferDataFromWindow(), wxValidator, Validate()
     */
@@ -2522,7 +2511,7 @@ public:
             Numeric identifier of the hotkey. Must be the same id that was passed to
         RegisterHotKey.
 
-        @returns @true if the hotkey was unregistered successfully, @false if the
+        @return @true if the hotkey was unregistered successfully, @false if the
                  id was invalid.
 
         @remarks This function is currently only implemented under MSW.
@@ -2533,15 +2522,15 @@ public:
 
     /**
         Unreserve an ID or range of IDs that was reserved by NewControlId().
-        See @ref overview_windowidsoverview "Window IDs overview" for more information.
+        See @ref overview_windowids "Window IDs Overview" for more information.
 
         @param id
             The starting ID of the range of IDs to unreserve.
         @param count
             The number of sequential IDs to unreserve.
 
-        @see NewControlId(), wxIdManager, @ref overview_windowidsoverview
-             "Window IDs overview"
+        @see NewControlId(), wxIdManager, @ref overview_windowids
+             "Window IDs Overview"
     */
     static void UnreserveControlId(wxWindowID id, int count = 1);
 
@@ -2587,7 +2576,7 @@ public:
         If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set,
         the method will also call Validate() of all child windows.
 
-        @returns Returns @false if any of the validations failed.
+        @return Returns @false if any of the validations failed.
 
         @see TransferDataFromWindow(), TransferDataToWindow(),
              wxValidator
@@ -2596,7 +2585,7 @@ public:
 
     /**
         Moves the pointer to the given position on the window.
-        @b NB: This function is not supported under Mac because Apple Human
+        @note This function is not supported under Mac because Apple Human
         Interface Guidelines forbid moving the mouse cursor programmatically.
 
         @param x
@@ -2608,6 +2597,32 @@ public:
 };
 
 
+/// Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
+enum wxShowEffect
+{
+    /// Roll window to the left
+    wxSHOW_EFFECT_ROLL_TO_LEFT,
+    /// Roll window to the right
+    wxSHOW_EFFECT_ROLL_TO_RIGHT,
+    /// Roll window to the top
+    wxSHOW_EFFECT_ROLL_TO_TOP,
+    /// Roll window to the bottom
+    wxSHOW_EFFECT_ROLL_TO_BOTTOM,
+    /// Slide window to the left
+    wxSHOW_EFFECT_SLIDE_TO_LEFT,
+    /// Slide window to the right
+    wxSHOW_EFFECT_SLIDE_TO_RIGHT,
+    /// Slide window to the top
+    wxSHOW_EFFECT_SLIDE_TO_TOP,
+    /// Slide window to the bottom
+    wxSHOW_EFFECT_SLIDE_TO_BOTTOM,
+    /// Fade in or out effect
+    wxSHOW_EFFECT_BLEND,
+    /// Expanding or collapsing effect
+    wxSHOW_EFFECT_EXPAND
+};
+
+
 
 // ============================================================================
 // Global functions/macros