Make wxGridSizer ctors more consistent.

The old and confusing wxGridSizer(int cols, int vgap = 0, int hgap = 0) is removed and replaced with wxGridSizer(int cols, int vgap, int hgap).

New ctor overloads using wxSize for the gap parameter added.

Closes #11040.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@61575 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -137,6 +137,12 @@ Changes in behaviour not resulting in compilation errors, please read this!
   class versions of these functions as this won't work any more; please see the
   documentation of wxLog for more information.
 
+- Confusing wxGridSizer(int cols, int vgap = 0, int hgap = 0) ctor which was
+  easy to mistake for wxGridSizer(int rows, int cols) overload was removed, you
+  will need to specify both vertical and horizontal gap if you want to use this
+  overload or specify both rows and columns and the gap otherwise. Use of the
+  new constructors taking wxSize for the gap argument is preferred.
+
 
 Changes in behaviour which may result in compilation errors
 -----------------------------------------------------------

include/wx/sizer.h

@@ -724,8 +724,14 @@ private:
 class WXDLLIMPEXP_CORE wxGridSizer: public wxSizer
 {
 public:
+    // ctors specifying the number of columns only: number of rows will be
+    // deduced automatically depending on the number of sizer elements
+    wxGridSizer( int cols, int vgap, int hgap );
+    wxGridSizer( int cols, const wxSize& gap = wxSize(0, 0) );
+
+    // ctors specifying the number of rows and columns
+    wxGridSizer( int rows, int cols, const wxSize& gap );
     wxGridSizer( int rows, int cols, int vgap, int hgap );
-    wxGridSizer( int cols, int vgap = 0, int hgap = 0 );
 
     virtual wxSizerItem *Insert(size_t index, wxSizerItem *item);
 

interface/wx/sizer.h

@@ -1578,16 +1578,27 @@ class wxGridSizer : public wxSizer
 public:
     //@{
     /**
-        Constructor for a wxGridSizer.
+        wxGridSizer 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.
+        Usually only the number of columns in the 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 the number of @a rows is explicitly specified (and not zero),
+        the sizer will check that it no more than @code cols*rows @endcode
+        elements are added to it.
 
-        @a vgap and @a hgap define extra space between all children.
+        The @a gap (or @a vgap and @a hgap which correspond to y and x fields
+        of the wxSize object) argument defines the size of the padding between
+        the grid 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 );
     //@}
 
     /**

src/common/sizer.cpp

@@ -1318,18 +1318,34 @@ bool wxSizer::IsShown( size_t index ) const
 //---------------------------------------------------------------------------
 
 wxGridSizer::wxGridSizer( int rows, int cols, int vgap, int hgap )
-    : m_rows( ( cols == 0 && rows == 0 ) ? 1 : rows )
-    , m_cols( cols )
-    , m_vgap( vgap )
-    , m_hgap( hgap )
+    : m_rows( rows || cols ? rows : 1 ),
+      m_cols( cols ),
+      m_vgap( vgap ),
+      m_hgap( hgap )
+{
+}
+
+wxGridSizer::wxGridSizer( int rows, int cols, const wxSize& gap )
+    : m_rows( rows || cols ? rows : 1 ),
+      m_cols( cols ),
+      m_vgap( gap.GetHeight() ),
+      m_hgap( gap.GetWidth() )
 {
 }
 
 wxGridSizer::wxGridSizer( int cols, int vgap, int hgap )
-    : m_rows( cols == 0 ? 1 : 0 )
-    , m_cols( cols )
-    , m_vgap( vgap )
-    , m_hgap( hgap )
+    : m_rows( cols == 0 ? 1 : 0 ),
+      m_cols( cols ),
+      m_vgap( vgap ),
+      m_hgap( hgap )
+{
+}
+
+wxGridSizer::wxGridSizer( int cols, const wxSize& gap )
+    : m_rows( cols == 0 ? 1 : 0 ),
+      m_cols( cols ),
+      m_vgap( gap.GetHeight() ),
+      m_hgap( gap.GetWidth() )
 {
 }