Add a simple wxGrid::AssignTable() wrapper for SetTable()

In many case SetTable() is called with its takeOwnership parameter set
to true, as shown by the grid sample in which all 3 of the calls to
SetTable() set it to true, but calling it in this case is awkward, as
bare "true" in the caller is unreadable and almost invariably requires
an explanatory comment.

Improve the API by adding AssignTable(), which is the same to SetTable()
as the existing AssignImageList() to SetImageLabel(), which always takes
ownership of the table pointer.

include/wx/generic/grid.h

@@ -1075,12 +1075,13 @@ public:
 
     virtual ~wxGrid();
 
-    // however to initialize grid data either CreateGrid() or SetTable() must
+    // however to initialize grid data either CreateGrid() (to use a simple
+    // default table class) or {Set,Assign}Table() (to use a custom table) must
     // be also called
 
     // this is basically equivalent to
     //
-    //   SetTable(new wxGridStringTable(numRows, numCols), true, selmode)
+    //   AssignTable(new wxGridStringTable(numRows, numCols), selmode)
     //
     bool CreateGrid( int numRows, int numCols,
                      wxGridSelectionModes selmode = wxGridSelectCells );
@@ -1089,6 +1090,9 @@ public:
                    bool takeOwnership = false,
                    wxGridSelectionModes selmode = wxGridSelectCells );
 
+    void AssignTable( wxGridTableBase *table,
+                      wxGridSelectionModes selmode = wxGridSelectCells );
+
     bool ProcessTableMessage(wxGridTableMessage&);
 
     wxGridTableBase *GetTable() const { return m_table; }

interface/wx/grid.h

@@ -2550,14 +2550,14 @@ public:
         Default constructor.
 
         You must call Create() to really create the grid window and also call
-        CreateGrid() or SetTable() to initialize the grid contents.
+        CreateGrid() or SetTable() or AssignTable() to initialize its contents.
      */
     wxGrid();
     /**
         Constructor creating the grid window.
 
-        You must call either CreateGrid() or SetTable() to initialize the grid
+        You must call either CreateGrid() or SetTable() or AssignTable() to
-        contents before using it.
+        initialize the grid contents before using it.
     */
     wxGrid(wxWindow* parent, wxWindowID id,
            const wxPoint& pos = wxDefaultPosition,
@@ -2578,8 +2578,8 @@ public:
         Creates the grid window for an object initialized using the default
         constructor.
 
-        You must call either CreateGrid() or SetTable() to initialize the grid
+        You must call either CreateGrid() or SetTable() or AssignTable() to
-        contents before using it.
+        initialize the grid contents before using it.
      */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
@@ -2596,7 +2596,8 @@ public:
 
         For applications with more complex data types or relationships, or for
         dealing with very large datasets, you should derive your own grid table
-        class and pass a table object to the grid with SetTable().
+        class and pass a table object to the grid with SetTable() or
+        AssignTable().
     */
     bool CreateGrid(int numRows, int numCols,
                     wxGridSelectionModes selmode = wxGridSelectCells);
@@ -2611,10 +2612,34 @@ public:
         Use this function instead of CreateGrid() when your application
         involves complex or non-string data or data sets that are too large to
         fit wholly in memory.
+
+        When the custom table should be owned by the grid, consider using the
+        simpler AssignTable() function instead of this one with @true value of
+        @a takeOwnership parameter.
     */
     bool SetTable(wxGridTableBase* table, bool takeOwnership = false,
                   wxGridSelectionModes selmode = wxGridSelectCells);
 
+    /**
+        Assigns a pointer to a custom grid table to be used by the grid.
+
+        This function is identical to SetTable() with @c takeOwnership
+        parameter set to @true, i.e. it simply always takes the ownership of
+        the passed in pointer. This makes it simpler to use than SetTable() in
+        the common case when the table should be owned by the grid object.
+
+        Note that this function should be called at most once and can't be used
+        to change the table used by the grid later on or reset it: if such
+        extra flexibility is needed, use SetTable() directly.
+
+        @since 3.1.4
+
+        @param table The heap-allocated pointer to the table.
+        @param selmode Selection mode to use.
+    */
+    void AssignTable( wxGridTableBase *table,
+                      wxGridSelectionModes selmode = wxGridSelectCells);
+
     /**
        Receive and handle a message from the table.
     */
@@ -5081,7 +5106,7 @@ public:
         successful the table notifies the grid and the grid updates the
         display. For a default grid (one where you have called CreateGrid())
         this process is automatic. If you are using a custom grid table
-        (specified with SetTable()) then you must override
+        (specified with SetTable() or AssignTable()) then you must override
         wxGridTableBase::InsertCols() in your derived table class.
 
         @param pos

samples/grid/griddemo.cpp

@@ -1686,7 +1686,7 @@ BigGridFrame::BigGridFrame(long sizeGrid)
     //     must profile it...
     //m_table->SetAttrProvider(new MyGridCellAttrProvider);
 
-    m_grid->SetTable(m_table, true);
+    m_grid->AssignTable(m_table);
 
 #if defined __WXMOTIF__
     // MB: the grid isn't getting a sensible default size under wxMotif
@@ -1977,7 +1977,7 @@ BugsGridFrame::BugsGridFrame()
     wxGrid *grid = new wxGrid(this, wxID_ANY);
     wxGridTableBase *table = new BugsGridTable();
     table->SetAttrProvider(new MyGridCellAttrProvider);
-    grid->SetTable(table, true);
+    grid->AssignTable(table);
 
     wxGridCellAttr *attrRO = new wxGridCellAttr,
                    *attrRangeEditor = new wxGridCellAttr,
@@ -2338,7 +2338,7 @@ TabularGridFrame::TabularGridFrame()
     m_grid = new wxGrid(panel, wxID_ANY,
                         wxDefaultPosition, wxDefaultSize,
                         wxBORDER_STATIC | wxWANTS_CHARS);
-    m_grid->SetTable(m_table, true, wxGrid::wxGridSelectRows);
+    m_grid->AssignTable(m_table, wxGrid::wxGridSelectRows);
 
     m_grid->EnableDragColMove();
     m_grid->UseNativeColHeader();

src/generic/grid.cpp

@@ -2601,6 +2601,14 @@ wxGrid::SetTable(wxGridTableBase *table,
     return m_created;
 }
 
+void wxGrid::AssignTable(wxGridTableBase *table, wxGridSelectionModes selmode)
+{
+    wxCHECK_RET( table, wxS("Table pointer must be valid") );
+    wxCHECK_RET( !m_created, wxS("wxGrid already has a table") );
+
+    SetTable(table, true /* take ownership */, selmode);
+}
+
 void wxGrid::Init()
 {
     m_created = false;