More interface header reviews by Azriel Fasten, along with a simple item "add" group...

[wxWidgets.git] / interface / window.h

diff --git a/interface/window.h b/interface/window.h
index 39677f024f5afdc83bab1f0dfdfe7e4bf11b4887..329d483714112e27b994d0baf2db8e801aa933ce 100644 (file)
--- a/interface/window.h
+++ b/interface/window.h
@@ -33,37 +33,37 @@
     changes the behaviour of the latter.
 
     @beginStyleTable
     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.
            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.
            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.
            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.
            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.
            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.
            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.
            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.
            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.
            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.
            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
            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


@@ -71,27 +71,27 @@
            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.
            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.
            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.
            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.
            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.
            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.
            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
            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


@@ -102,25 +102,25 @@
     @endStyleTable
 
     @beginExtraStyleTable
     @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.
            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.
            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.
            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.
            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.
            This window should always process UI update events, even if the
            mode set by wxUpdateUIEvent::SetMode is
            wxUPDATE_UI_PROCESS_SPECIFIED.


@@ -212,7 +212,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.
 
         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.
 
         @param hflag
             Whether the horizontal scroll bar should always be visible.


@@ -445,6 +445,20 @@ 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().
         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;
 
     */
     virtual wxSize DoGetBestSize() const;
 


@@ -544,13 +558,22 @@ public:
                                       wxWindow* parent = NULL);
 
     /**
                                       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.
+
+        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:

 
 

-        instead of calling Fit.
+        @begincode
+            window->SetClientSize(child->GetSize());
+        @endcode
+
+        instead of calling Fit().
+
+        @see @ref overview_windowsizing

     */
     virtual void Fit();
 
     */
     virtual void Fit();
 


@@ -596,8 +619,7 @@ public:
     wxAccessible* GetAccessible();
 
     /**
     wxAccessible* GetAccessible();
 
     /**

-        This method is deprecated, use GetEffectiveMinSize()
-        instead.
+        This method is deprecated, use GetEffectiveMinSize() instead.

     */
     wxSize GetAdjustedBestSize() const;
 
     */
     wxSize GetAdjustedBestSize() const;
 


@@ -697,7 +719,7 @@ public:
         ignore under other platforms. Under Mac, it will change the size of the
         returned font. See SetWindowVariant()
         for more about this.
         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().
         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().


@@ -755,7 +777,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
         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
         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


@@ -771,11 +793,11 @@ public:
     wxDropTarget* GetDropTarget() const;
 
     /**
     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.
 
         ammount of space to allocate for the widget.
 

-        @see GetBestSize(), SetInitialSize()
+        @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing

     */
     wxSize GetEffectiveMinSize() const;
 
     */
     wxSize GetEffectiveMinSize() const;
 


@@ -929,7 +951,7 @@ public:
         Returns the next window after this one among the parent children or @NULL if
         this window is the last child.
 
         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()
     */
 
         @see GetPrevSibling()
     */


@@ -986,7 +1008,7 @@ public:
         @NULL if
         this window is the first child.
 
         @NULL if
         this window is the first child.
 

-        @wxsince{2.8.8}
+        @since 2.8.8

 
         @see GetNextSibling()
     */
 
         @see GetNextSibling()
     */


@@ -1239,7 +1261,7 @@ public:
         ShowWithEffect(), please see their
         description there.
 
         ShowWithEffect(), please see their
         description there.
 

-        @wxsince{2.9.0}
+        @since 2.9.0

     */
     virtual bool HideWithEffect(wxShowEffect effect,
                                 unsigned timeout = 0,
     */
     virtual bool HideWithEffect(wxShowEffect effect,
                                 unsigned timeout = 0,


@@ -1249,7 +1271,7 @@ public:
         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.
         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
+        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
         own @ref getclassdefaultattributes() default attributes. However
         if some of the parents attributes are explicitly (that is, using
         SetFont() and not


@@ -1375,21 +1397,13 @@ public:
     /**
         Invokes the constraint-based layout algorithm or the sizer-based algorithm
         for this window.
     /**
         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.
-    */
-    void Layout();
-
-    /**
-        This is just a wrapper for wxWindow::ScrollLines(1).
-    */

 
 

+        See SetAutoLayout(): when auto layout is on, this function gets called automatically
+        when the window is resized.

 
 

-    /**
-        This is just a wrapper for wxWindow::ScrollLines(-1).
+        @see @ref overview_windowsizing

     */
     */

-
+    void Layout();

 
     /**
         Lowers the window to the bottom of the window hierarchy (Z-order).
 
     /**
         Lowers the window to the bottom of the window hierarchy (Z-order).


@@ -1508,13 +1522,24 @@ public:
     virtual void OnInternalIdle();
 
     /**
     virtual void OnInternalIdle();
 
     /**

-        This is just a wrapper for wxWindow::ScrollPages(1).
+        Same as #ScrollLines (-1).
+    */
+    bool LineUp();
+
+    /**
+        Same as #ScrollLines (1).

     */
     */

+    bool LineDown();

 
 

+    /**
+        Same as #ScrollPages (-1).
+    */
+    bool PageUp();

 
     /**
 
     /**

-        This is just a wrapper for wxWindow::ScrollPages(-1).
+        Same as #ScrollPages (1).

     */
     */

+    bool PageDown();

 
 
     /**
 
 
     /**


@@ -1715,8 +1740,8 @@ public:
                  on top/bottom and nothing was done.
 
         @remarks This function is currently only implemented under MSW and
                  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()
     */
 
         @see ScrollPages()
     */


@@ -1747,8 +1772,8 @@ public:
             scrolled (this is always the case under wxGTK which doesn't support this
             parameter)
 
             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);
     */
     virtual void ScrollWindow(int dx, int dy,
                               const wxRect* rect = NULL);


@@ -2030,7 +2055,7 @@ public:
         implementation,
         and not in the window object itself.
 
         implementation,
         and not in the window object itself.
 

-        @see GetHelpText(), wxHelpProvider
+        @see GetHelpText(), wxHelpProvider::AddHelp()

     */
     virtual void SetHelpText(const wxString& helpText);
 
     */
     virtual void SetHelpText(const wxString& helpText);
 


@@ -2054,15 +2079,18 @@ public:
 
     /**
         A @e smart SetSize that will fill in default size components with the
 
     /**
         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.)
 
         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);
 
     */
     void SetInitialSize(const wxSize& size = wxDefaultSize);
 


@@ -2166,8 +2194,8 @@ public:
                  window: it is up to the application to take note of
                  scrollbar attributes and redraw contents accordingly.
 
                  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);
     */
     virtual void SetScrollPos(int orientation, int pos,
                               bool refresh = true);


@@ -2191,8 +2219,7 @@ public:
                  font. The window is sized so that you can only see 16
                  lines at a time.
 
                  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,
     */
     virtual void SetScrollbar(int orientation, int position,
                               int thumbSize,


@@ -2457,7 +2484,7 @@ public:
         Currently this function is only implemented in wxMSW and does the same thing as
         Show() in the other ports.
 
         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()
     */
 
         @see HideWithEffect()
     */


@@ -2595,7 +2622,7 @@ public:
 
     /**
         Moves the pointer to the given position on the window.
 
     /**
         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
         Interface Guidelines forbid moving the mouse cursor programmatically.
 
         @param x


@@ -2612,27 +2639,32 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/**
-    Find the deepest window at the given mouse position in screen coordinates,
-    returning the window if found, or @NULL if not.
-*/
-wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
+/** @ingroup group_funcmacro_misc */
+//@{

 
 /**
     Find the deepest window at the mouse pointer position, returning the window
     and current pointer position in screen coordinates.
 
 /**
     Find the deepest window at the mouse pointer position, returning the window
     and current pointer position in screen coordinates.

+
+    @header{wx/window.h}

 */
 wxWindow* wxFindWindowAtPointer(wxPoint& pt);
 
 /**
 */
 wxWindow* wxFindWindowAtPointer(wxPoint& pt);
 
 /**

-    Gets the currently active window (implemented for MSW and GTK only currently,
-    always returns @NULL in the other ports).
+    Gets the currently active window (implemented for MSW and GTK only
+    currently, always returns @NULL in the other ports).
+
+    @header{wx/window.h}

 */
 wxWindow* wxGetActiveWindow();
 
 /**
 */
 wxWindow* wxGetActiveWindow();
 
 /**

-    Returns the first top level parent of the given window, or in other words, the
-    frame or dialog containing it, or @NULL.
+    Returns the first top level parent of the given window, or in other words,
+    the frame or dialog containing it, or @NULL.
+
+    @header{wx/window.h}

 */
 */

-wxWindow* wxGetTopLevelParent(wxWindow win);
+wxWindow* wxGetTopLevelParent(wxWindow* window);
+
+//@}