Ticket #9592: gtk-choice-setcolumns.2.diff

[wxWidgets.git] / interface / window.h

diff --git a/interface/window.h b/interface/window.h
index 79235c42cad76769405c69be9eef67df418c06a4..30102c6bab213fa57934c378f0f0792e36a20673 100644 (file)
--- a/interface/window.h
+++ b/interface/window.h
@@ -17,13 +17,11 @@
     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
     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,
 
     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
     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


@@ -129,13 +127,17 @@
     @library{wxcore}
     @category{FIXME}
 
     @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:
 */
 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.
     /**
         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.
     */
         @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);
     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
 
     /**
         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.
 
         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();
              Destroy(), wxCloseEvent
     */
     ~wxWindow();


@@ -187,7 +187,7 @@ public:
 
         @see AcceptsFocusFromKeyboard()
     */
 
         @see AcceptsFocusFromKeyboard()
     */

-    bool AcceptsFocus() const;
+    virtual bool AcceptsFocus() const;

 
     /**
         This method may be overridden in the derived classes to return @false to
 
     /**
         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.
     */
         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.
     /**
         Adds a child window.  This is called automatically by window creation
         functions so should not be required by the application programmer.


@@ -319,8 +326,8 @@ public:
         @param pt
             The client position for the second form of the function.
     */
         @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.
 
                  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);
              Destroy(), wxCloseEvent
     */
     bool Close(bool force = false);


@@ -434,7 +441,7 @@ public:
     virtual void DestroyChildren();
 
     /**
     virtual void DestroyChildren();
 
     /**

-        Disables the window, same as @ref enable() Enable(@false).
+        Disables the window. Same as @ref Enable() Enable(@false).

 
         @return Returns @true if the window has been disabled, @false if it had
                  been already disabled before the call to this function.
 
         @return Returns @true if the window has been disabled, @false if it had
                  been already disabled before the call to this function.


@@ -464,11 +471,8 @@ public:
 
     /**
         Does the window-specific updating after processing the update event.
 
     /**
         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);
 
     */
     virtual void DoUpdateWindowUI(wxUpdateUIEvent& event);
 


@@ -509,13 +513,18 @@ public:
     */
     static wxWindow* FindFocus();
 
     */
     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;
     */
     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.
 
     /**
         Find the first window with the given @e id.


@@ -567,7 +576,7 @@ public:
         is more precise as Fit() adds some margin to account for fuzziness of its calculations)
         to call:
 
         is more precise as Fit() adds some margin to account for fuzziness of its calculations)
         to call:
 

-        @begincode
+        @code

             window->SetClientSize(child->GetSize());
         @endcode
 
             window->SetClientSize(child->GetSize());
         @endcode
 


@@ -629,7 +638,7 @@ public:
         @see SetBackgroundColour(), SetForegroundColour(),
              GetForegroundColour()
     */
         @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:
 
     /**
         Returns the background style of the window. The background style can be one of:


@@ -702,11 +711,10 @@ public:
     //@{
     /**
         Returns a reference to the list of the window's children. @c wxWindowList
     //@{
     /**
         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;

     //@}
 
     /**
     //@}
 
     /**


@@ -749,7 +757,7 @@ public:
         @see GetSize(), GetVirtualSize()
     */
     void GetClientSize(int* width, int* height) const;
         @see GetSize(), GetVirtualSize()
     */
     void GetClientSize(int* width, int* height) const;

-    const wxSize  GetClientSize() const;
+    wxSize GetClientSize() const;

     //@}
 
     /**
     //@}
 
     /**


@@ -761,14 +769,14 @@ public:
         Return the sizer that this window is a member of, if any, otherwise
         @NULL.
     */
         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()
     */
 
     /**
         Return the cursor associated with this window.
 
         @see SetCursor()
     */

-    const wxCursor GetCursor() const;
+    const wxCursor& GetCursor() const;

 
     /**
         Currently this is the same as calling
 
     /**
         Currently this is the same as calling


@@ -788,7 +796,7 @@ public:
     /**
         Returns the associated drop target, which may be @NULL.
 
     /**
         Returns the associated drop target, which may be @NULL.
 

-        @see SetDropTarget(), @ref overview_wxdndoverview
+        @see SetDropTarget(), @ref overview_dnd

     */
     wxDropTarget* GetDropTarget() const;
 
     */
     wxDropTarget* GetDropTarget() const;
 


@@ -833,7 +841,7 @@ public:
         @see SetForegroundColour(), SetBackgroundColour(),
              GetBackgroundColour()
     */
         @see SetForegroundColour(), SetBackgroundColour(),
              GetBackgroundColour()
     */

-    virtual wxColour GetForegroundColour();
+    wxColour GetForegroundColour();

 
     /**
         Returns the grandparent of a window, or @NULL if there isn't one.
 
     /**
         Returns the grandparent of a window, or @NULL if there isn't one.


@@ -927,10 +935,10 @@ public:
 
     /**
         Returns the minimum size of the window, an indication to the sizer layout
 
     /**
         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()
     */
 
         @see GetMinClientSize()
     */


@@ -999,8 +1007,8 @@ public:
 
         @see GetScreenPosition()
     */
 
         @see GetScreenPosition()
     */

-    virtual void GetPosition(int* x, int* y) const;
-    const wxPoint  GetPosition() const;
+    void GetPosition(int* x, int* y) const;
+    wxPoint GetPosition() const;

     //@}
 
     /**
     //@}
 
     /**


@@ -1019,7 +1027,7 @@ public:
 
         @see GetScreenRect()
     */
 
         @see GetScreenRect()
     */

-    virtual wxRect GetRect() const;
+    wxRect GetRect() const;

 
     //@{
     /**
 
     //@{
     /**


@@ -1033,8 +1041,8 @@ public:
 
         @see GetPosition()
     */
 
         @see GetPosition()
     */

-    virtual void GetScreenPosition(int* x, int* y) const;
-    const wxPoint  GetScreenPosition() const;
+    void GetScreenPosition(int* x, int* y) const;
+    wxPoint GetScreenPosition() const;

     //@}
 
     /**
     //@}
 
     /**


@@ -1043,7 +1051,7 @@ public:
 
         @see GetRect()
     */
 
         @see GetRect()
     */

-    virtual wxRect GetScreenRect() const;
+    wxRect GetScreenRect() const;

 
     /**
         Returns the built-in scrollbar position.
 
     /**
         Returns the built-in scrollbar position.


@@ -1271,7 +1279,7 @@ public:
         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
         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
+        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
         if some of the parents attributes are explicitly (that is, using
         SetFont() and not
         wxWindow::SetOwnFont) changed and if the


@@ -1380,7 +1388,7 @@ public:
     /**
         Returns @true if this window is intrinsically enabled, @false otherwise,
         i.e.
     /**
         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.
     */
         mostly used for wxWidgets itself, user code should normally use
         IsEnabled() instead.
     */


@@ -1496,7 +1504,7 @@ 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().
         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.
 
         @param count
             The number of sequential IDs to reserve.


@@ -1504,8 +1512,8 @@ public:
         @return Returns the ID or the first ID of the range, or wxID_NONE if the
                  specified number of identifiers couldn't be allocated.
 
         @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);
 
     */
     static wxWindowID NewControlId(int count = 1);
 


@@ -1919,7 +1927,7 @@ public:
         Associates a drop target with this window.
         If the window already has a drop target, it is deleted.
 
         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);
 
     */
     void SetDropTarget(wxDropTarget* target);
 


@@ -1958,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
         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
 
 
         @b wxWS_EX_TRANSIENT
 


@@ -2122,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
     /**
         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.
 
         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);
 
     /**
         @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()
     */
 
         @see SetMinClientSize()
     */


@@ -2286,16 +2306,6 @@ public:
     virtual void SetSize(const wxSize& size);
     //@}
 
     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.
     /**
         Sets the window to have the given layout sizer. The window
         will then own the object, and will take care of its deletion.


@@ -2307,13 +2317,11 @@ public:
 
         @param sizer
             The sizer to set. Pass @NULL to disassociate and conditionally delete
 
         @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.
         @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);
 
     */
     void SetSizer(wxSizer* sizer, bool deleteOld = true);
 


@@ -2374,34 +2382,6 @@ public:
     void SetVirtualSize(const wxSize& size);
     //@}
 
     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().
     */
     /**
         Identical to SetWindowStyleFlag().
     */


@@ -2542,15 +2522,15 @@ public:
 
     /**
         Unreserve an ID or range of IDs that was reserved by NewControlId().
 
     /**
         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.
 
 
         @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);
 
     */
     static void UnreserveControlId(wxWindowID id, int count = 1);