Make wxTopLevelWindow::GetDefaultSize() public and document it.

[wxWidgets.git] / interface / wx / sizer.h

diff --git a/interface/wx/sizer.h b/interface/wx/sizer.h
index b0a44268082086e17deedaa24ac050cda69cff0b..719d4d2c4a6c40f050d6f6018a77a96f25f4003a 100644 (file)
--- a/interface/wx/sizer.h
+++ b/interface/wx/sizer.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxStdDialogButtonSizer
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxStdDialogButtonSizer
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -291,13 +291,15 @@ public:
                      wxObject* userData = NULL);
 
     /**
                      wxObject* userData = NULL);
 
     /**

-        Adds non-stretchable space to the sizer.
+        This base function adds non-stretchable space to both the horizontal
+        and vertical orientation of the sizer.

         More readable way of calling:
         @code
         wxSizer::Add(size, size, 0).
         @endcode
         More readable way of calling:
         @code
         wxSizer::Add(size, size, 0).
         @endcode

+        @see wxBoxSizer::AddSpacer()

     */
     */

-    wxSizerItem* AddSpacer(int size);
+    virtual wxSizerItem *AddSpacer(int size);

 
     /**
         Adds stretchable space to the sizer.
 
     /**
         Adds stretchable space to the sizer.


@@ -568,7 +570,7 @@ public:
 
     /**
         Inserts non-stretchable space to the sizer.
 
     /**
         Inserts non-stretchable space to the sizer.

-        More readable way of calling wxSizer::Insert(size, size, 0).
+        More readable way of calling wxSizer::Insert(index, size, size).

     */
     wxSizerItem* InsertSpacer(size_t index, int size);
 
     */
     wxSizerItem* InsertSpacer(size_t index, int size);
 


@@ -783,35 +785,28 @@ public:
     /**
         Set an item's minimum size by window, sizer, or position.
 
     /**
         Set an item's minimum size by window, sizer, or position.
 

-        The item will be found recursively in the sizer's descendants.

         This function enables an application to set the size of an item after
         initial creation.
 
         This function enables an application to set the size of an item after
         initial creation.
 

+        The @a window or @a sizer will be found recursively in the sizer's
+        descendants.
+

         @see wxSizerItem::SetMinSize()
         @see wxSizerItem::SetMinSize()

+
+        @return
+            @true if the minimal size was successfully set or @false if the
+            item was not found.

     */
     */

+    //@{

     bool SetItemMinSize(wxWindow* window, int width, int height);
     bool SetItemMinSize(wxWindow* window, int width, int height);

+    bool SetItemMinSize(wxWindow* window, const wxSize& size);

 
 

-    /**
-        Set an item's minimum size by window, sizer, or position.
-
-        The item will be found recursively in the sizer's descendants.
-        This function enables an application to set the size of an item after
-        initial creation.
-
-        @see wxSizerItem::SetMinSize()
-    */

     bool SetItemMinSize(wxSizer* sizer, int width, int height);
     bool SetItemMinSize(wxSizer* sizer, int width, int height);

+    bool SetItemMinSize(wxSizer* sizer, const wxSize& size);

 
 

-    /**
-        Set an item's minimum size by window, sizer, or position.
-
-        The item will be found recursively in the sizer's descendants.
-        This function enables an application to set the size of an item after
-        initial creation.
-
-        @see wxSizerItem::SetMinSize()
-    */

     bool SetItemMinSize(size_t index, int width, int height);
     bool SetItemMinSize(size_t index, int width, int height);

+    bool SetItemMinSize(size_t index, const wxSize& size);
+    //@}

 
     /**
         Call this to give the sizer a minimal size.
 
     /**
         Call this to give the sizer a minimal size.


@@ -1022,6 +1017,30 @@ public:
     */
     virtual ~wxSizerItem();
 
     */
     virtual ~wxSizerItem();
 

+    /**
+        Set the window to be tracked by this item.
+
+        The old window isn't deleted as it is now owned by the sizer item.
+    */
+    void AssignWindow(wxWindow *window);
+
+    /**
+        Set the sizer tracked by this item.
+
+        Old sizer, if any, is deleted.
+    */
+    void AssignSizer(wxSizer *sizer);
+
+    //@{
+    /**
+        Set the size of the spacer tracked by this item.
+
+        Old spacer, if any, is deleted.
+    */
+    void AssignSpacer(const wxSize& size);
+    void AssignSpacer(int w, int h) { AssignSpacer(wxSize(w, h)); }
+    //@}
+

     /**
         Calculates the minimum desired size for the item, including any space
         needed by borders.
     /**
         Calculates the minimum desired size for the item, including any space
         needed by borders.


@@ -1191,13 +1210,17 @@ public:
 
     /**
         Set the sizer tracked by this item.
 
     /**
         Set the sizer tracked by this item.

-        @deprecated @todo provide deprecation description
+
+        @deprecated This function does not free the old sizer which may result
+        in memory leaks, use AssignSizer() which does free it instead.

     */
     void SetSizer(wxSizer* sizer);
 
     /**
         Set the size of the spacer tracked by this item.
     */
     void SetSizer(wxSizer* sizer);
 
     /**
         Set the size of the spacer tracked by this item.

-        @deprecated @todo provide deprecation description
+
+        @deprecated This function does not free the old spacer which may result
+        in memory leaks, use AssignSpacer() which does free it instead.

     */
     void SetSpacer(const wxSize& size);
 
     */
     void SetSpacer(const wxSize& size);
 


@@ -1394,6 +1417,21 @@ public:
 };
 
 
 };
 
 

+/**
+    Values which define the behaviour for resizing wxFlexGridSizer cells in the
+    "non-flexible" direction.
+*/
+enum wxFlexSizerGrowMode
+{
+    /// Don't resize the cells in non-flexible direction at all.
+    wxFLEX_GROWMODE_NONE,
+
+    /// Uniformly resize only the specified ones (default).
+    wxFLEX_GROWMODE_SPECIFIED,
+
+    /// Uniformly resize all cells.
+    wxFLEX_GROWMODE_ALL
+};

 
 /**
     @class wxFlexGridSizer
 
 /**
     @class wxFlexGridSizer


@@ -1420,17 +1458,17 @@ class wxFlexGridSizer : public wxGridSizer
 public:
     //@{
     /**
 public:
     //@{
     /**

-        Constructor for a wxFlexGridSizer.
+        wxFlexGridSizer constructors.

 
 

-        @a rows and @a cols determine the number of columns and rows in the sizer -
-        if either of the parameters is zero, it will be calculated to form the
-        total number of children in the sizer, thus making the sizer grow
-        dynamically.
+        Please see wxGridSizer::wxGridSizer documentation.

 
 

-        @a vgap and @a hgap define extra space between all children.
+        @since 2.9.1 (except for the four argument overload)

     */
     */

-    wxFlexGridSizer(int rows, int cols, int vgap, int hgap);
-    wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0);
+    wxFlexGridSizer( int cols, int vgap, int hgap );
+    wxFlexGridSizer( int cols, const wxSize& gap = wxSize(0, 0) );
+
+    wxFlexGridSizer( int rows, int cols, int vgap, int hgap );
+    wxFlexGridSizer( int rows, int cols, const wxSize& gap );

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


@@ -1438,10 +1476,10 @@ public:
         there is extra space available to the sizer.
 
         The @a proportion parameter has the same meaning as the stretch factor
         there is extra space available to the sizer.
 
         The @a proportion parameter has the same meaning as the stretch factor

-        for the sizers() except that if all proportions are 0, then all columns
-        are resized equally (instead of not being resized at all).
+        for the sizers (see wxBoxSizer) except that if all proportions are 0,
+        then all columns are resized equally (instead of not being resized at all).

 
 

-        Notice that the row must not be already growable, if you need to change
+        Notice that the column must not be already growable, if you need to change

         the proportion you must call RemoveGrowableCol() first and then make it
         growable (with a different proportion) again. You can use IsColGrowable()
         to check whether a column is already growable.
         the proportion you must call RemoveGrowableCol() first and then make it
         growable (with a different proportion) again. You can use IsColGrowable()
         to check whether a column is already growable.


@@ -1458,7 +1496,7 @@ public:
     void AddGrowableRow(size_t idx, int proportion = 0);
 
     /**
     void AddGrowableRow(size_t idx, int proportion = 0);
 
     /**

-        Returns a wxOrientation value that specifies whether the sizer flexibly
+        Returns a ::wxOrientation value that specifies whether the sizer flexibly

         resizes its columns, rows, or both (default).
 
         @return
         resizes its columns, rows, or both (default).
 
         @return


@@ -1476,8 +1514,8 @@ public:
         direction if there is one.
 
         The behaviour of the elements in the flexible direction (i.e. both rows
         direction if there is one.
 
         The behaviour of the elements in the flexible direction (i.e. both rows

-        and columns by default, or rows only if GetFlexibleDirection() is @c
-        wxVERTICAL or columns only if it is @c wxHORIZONTAL) is always governed
+        and columns by default, or rows only if GetFlexibleDirection() is
+        @c wxVERTICAL or columns only if it is @c wxHORIZONTAL) is always governed

         by their proportion as specified in the call to AddGrowableRow() or
         AddGrowableCol(). What happens in the other direction depends on the
         value of returned by this function as described below.
         by their proportion as specified in the call to AddGrowableRow() or
         AddGrowableCol(). What happens in the other direction depends on the
         value of returned by this function as described below.


@@ -1513,12 +1551,12 @@ public:
     bool IsRowGrowable(size_t idx);
 
     /**
     bool IsRowGrowable(size_t idx);
 
     /**

-        Specifies that column idx is no longer growable.
+        Specifies that the @a idx column index is no longer growable.

     */
     void RemoveGrowableCol(size_t idx);
 
     /**
     */
     void RemoveGrowableCol(size_t idx);
 
     /**

-        Specifies that row idx is no longer growable.
+        Specifies that the @a idx row index is no longer growable.

     */
     void RemoveGrowableRow(size_t idx);
 
     */
     void RemoveGrowableRow(size_t idx);
 


@@ -1527,6 +1565,7 @@ public:
 
         Argument @a direction can be @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH
         (which is the default value). Any other value is ignored.
 
         Argument @a direction can be @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH
         (which is the default value). Any other value is ignored.

+

         See GetFlexibleDirection() for the explanation of these values.
         Note that this method does not trigger relayout.
     */
         See GetFlexibleDirection() for the explanation of these values.
         Note that this method does not trigger relayout.
     */


@@ -1562,32 +1601,82 @@ class wxGridSizer : public wxSizer
 public:
     //@{
     /**
 public:
     //@{
     /**

-        Constructor for a wxGridSizer.
+        wxGridSizer constructors.
+
+        Usually only the number of columns in the flex grid sizer needs to be
+        specified using @a cols argument. The number of rows will be deduced
+        automatically depending on the number of the elements added to the
+        sizer.
+
+        If a constructor form with @a rows parameter is used (and the value of
+        @a rows argument is not zero, meaning "unspecified") the sizer will
+        check that no more than @c cols*rows elements are added to it, i.e.
+        that no more than the given number of @a rows is used. Adding less than
+        maximally allowed number of items is not an error however.

 
 

-        @a rows and @a cols determine the number of columns and rows in the sizer -
-        if either of the parameters is zero, it will be calculated to form the
-        total number of children in the sizer, thus making the sizer grow dynamically.
+        Finally, it is also possible to specify the number of rows and use 0
+        for @a cols. In this case, the sizer will use the given fixed number of
+        rows and as many columns as necessary.

 
 

-        @a vgap and @a hgap define extra space between all children.
+        The @a gap (or @a vgap and @a hgap, which correspond to the height and
+        width of the wxSize object) argument defines the size of the padding
+        between the rows (its vertical component, or @a vgap) and columns
+        (its horizontal component, or @a hgap), in pixels.
+
+
+        @since 2.9.1 (except for the four argument overload)

     */
     */

-    wxGridSizer(int rows, int cols, int vgap, int hgap);
-    wxGridSizer(int cols, int vgap = 0, int hgap = 0);
+    wxGridSizer( int cols, int vgap, int hgap );
+    wxGridSizer( int cols, const wxSize& gap = wxSize(0, 0) );
+
+    wxGridSizer( int rows, int cols, int vgap, int hgap );
+    wxGridSizer( int rows, int cols, const wxSize& gap );

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

-        Returns the number of columns in the sizer.
+        Returns the number of columns that has been specified for the
+        sizer.
+
+        Returns zero if the sizer is automatically adjusting the number of
+        columns depending on number of its children. To get the effective
+        number of columns or rows being currently used, see GetEffectiveColsCount()

     */
     int GetCols() const;
     */
     int GetCols() const;

+    
+    /**
+        Returns the number of rows that has been specified for the
+        sizer.
+
+        Returns zero if the sizer is automatically adjusting the number of
+        rows depending on number of its children. To get the effective
+        number of columns or rows being currently used, see GetEffectiveRowsCount().
+    */
+    int GetRows() const;

 
     /**
 
     /**

-        Returns the horizontal gap (in pixels) between cells in the sizer.
+        Returns the number of columns currently used by the sizer.
+
+        This will depend on the number of children the sizer has if
+        the sizer is automatically adjusting the number of columns/rows.
+
+        @since 2.9.1

     */
     */

-    int GetHGap() const;
+    int GetEffectiveColsCount() const;
+    
+    /**
+        Returns the number of rows currently used by the sizer.
+
+        This will depend on the number of children the sizer has if
+        the sizer is automatically adjusting the number of columns/rows.
+
+        @since 2.9.1
+    */
+    int GetEffectiveRowsCount() const;

 
     /**
 
     /**

-        Returns the number of rows in the sizer.
+        Returns the horizontal gap (in pixels) between cells in the sizer.

     */
     */

-    int GetRows() const;
+    int GetHGap() const;

 
     /**
         Returns the vertical gap (in pixels) between the cells in the sizer.
 
     /**
         Returns the vertical gap (in pixels) between the cells in the sizer.


@@ -1620,11 +1709,29 @@ public:
 /**
     @class wxStaticBoxSizer
 
 /**
     @class wxStaticBoxSizer
 

-    wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static
-    box around the sizer.
-    This static box may be either created independently or the sizer may create
-    it itself as a convenience. In any case, the sizer owns the wxStaticBox control
-    and will delete it, if it is deleted.
+    wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box around
+    the sizer.
+
+    The static box may be either created independently or the sizer may create it
+    itself as a convenience. In any case, the sizer owns the wxStaticBox control
+    and will delete it in the wxStaticBoxSizer destructor.
+
+    Note that since wxWidgets 2.9.1 you are encouraged to create the windows
+    which are added to wxStaticBoxSizer as children of wxStaticBox itself, see
+    this class documentation for more details.
+
+    Example of use of this class:
+    @code
+        void MyFrame::CreateControls()
+        {
+            wxPanel *panel = new wxPanel(this);
+            ...
+            wxStaticBoxSizer *sz = new wxStaticBoxSizer(wxVERTICAL, panel, "Box");
+            sz->Add(new wxStaticText(sz->GetStaticBox(), wxID_ANY,
+                                     "This window is a child of the staticbox"));
+            ...
+        }
+    @endcode

 
     @library{wxcore}
     @category{winlayout}
 
     @library{wxcore}
     @category{winlayout}


@@ -1637,8 +1744,11 @@ public:
     /**
         This constructor uses an already existing static box.
 
     /**
         This constructor uses an already existing static box.
 

-        It takes the associated static box and the orientation @a orient, which
-        can be either @c wxVERTICAL or @c wxHORIZONTAL as parameters.
+        @param box
+            The static box to associate with the sizer (which will take its
+            ownership).
+        @param orient
+            Can be either @c wxVERTICAL or @c wxHORIZONTAL.

     */
     wxStaticBoxSizer(wxStaticBox* box, int orient);
 
     */
     wxStaticBoxSizer(wxStaticBox* box, int orient);
 


@@ -1679,6 +1789,22 @@ public:
     */
     wxBoxSizer(int orient);
 
     */
     wxBoxSizer(int orient);
 

+    /**
+        Adds non-stretchable space to the main orientation of the sizer only.
+        More readable way of calling:
+        @code
+        if ( wxBoxSizer::IsVertical() )
+        {
+            wxBoxSizer::Add(0, size, 0).
+        }
+        else
+        {
+            wxBoxSizer::Add(size, 0, 0).
+        }
+        @endcode
+    */
+    virtual wxSizerItem *AddSpacer(int size);
+

     /**
         Implements the calculation of a box sizer's minimal.
 
     /**
         Implements the calculation of a box sizer's minimal.