Tried to make wxDataViewModel docs clearer

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

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index 6ae0a936b1e01061eca76fffe3fe90d31d227814..5893ecebcbcde79b8df73955c11232d7de7718ca 100644 (file)
--- a/interface/wx/dataview.h
+++ b/interface/wx/dataview.h
@@ -20,17 +20,26 @@
     wxDataViewModel::GetValue in order to define the data model which acts as an
     interface between your actual data and the wxDataViewCtrl.
 
     wxDataViewModel::GetValue in order to define the data model which acts as an
     interface between your actual data and the wxDataViewCtrl.
 

-    Since you will usually also allow the wxDataViewCtrl to change your data
-    through its graphical interface, you will also have to override
-    wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
-    to some data has been committed.
+    Note that wxDataViewModel does not define the position or index of any item
+    in the control because different controls might display the same data differently.
+    wxDataViewModel does provide a wxDataViewModel::Compare method which the
+    wxDataViewCtrl may use to sort the data either in conjunction with a column
+    header or without (see wxDataViewModel::HasDefaultCompare).

 
     wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
     to store data and its type in a generic way. wxVariant can be extended to contain
 
     wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
     to store data and its type in a generic way. wxVariant can be extended to contain

-    almost any data without changes to the original class.
+    almost any data without changes to the original class. To a certain extent,
+    you can use (the somewhat more elegant) wxAny instead of wxVariant as there
+    is code to convert between the two, but it is unclear what impact this will
+    have on performance.
+
+    Since you will usually allow the wxDataViewCtrl to change your data
+    through its graphical interface, you will also have to override
+    wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
+    to some data has been committed.

 
 

-    The data that is presented through this data model is expected to change at
-    run-time. You need to inform the data model when a change happened.
+    If the data represented by the model is changed by something else than its
+    associated wxDataViewCtrl, the control has to be notified about the change.

     Depending on what happened you need to call one of the following methods:
     - wxDataViewModel::ValueChanged,
     - wxDataViewModel::ItemAdded,
     Depending on what happened you need to call one of the following methods:
     - wxDataViewModel::ValueChanged,
     - wxDataViewModel::ItemAdded,


@@ -44,12 +53,6 @@
     - wxDataViewModel::ItemsDeleted,
     - wxDataViewModel::ItemsChanged.
 
     - wxDataViewModel::ItemsDeleted,
     - wxDataViewModel::ItemsChanged.
 

-    Note that wxDataViewModel does not define the position or index of any item
-    in the control because different controls might display the same data differently.
-    wxDataViewModel does provide a wxDataViewModel::Compare method which the
-    wxDataViewCtrl may use to sort the data either in conjunction with a column
-    header or without (see wxDataViewModel::HasDefaultCompare).
-

     This class maintains a list of wxDataViewModelNotifier which link this class
     to the specific implementations on the supported platforms so that e.g. calling
     wxDataViewModel::ValueChanged on this model will just call
     This class maintains a list of wxDataViewModelNotifier which link this class
     to the specific implementations on the supported platforms so that e.g. calling
     wxDataViewModel::ValueChanged on this model will just call


@@ -75,6 +78,19 @@
         // add columns now
     @endcode
 
         // add columns now
     @endcode
 

+    A potentially better way to avoid memory leaks is to use wxObjectDataPtr
+    
+    @code
+        wxObjectDataPtr<MyMusicModel> musicModel;
+        
+        wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
+        musicModel = new MyMusicModel;
+        m_musicCtrl->AssociateModel( musicModel.get() );
+
+        // add columns now
+    @endcode
+
+

     @library{wxadv}
     @category{dvc}
 */
     @library{wxadv}
     @category{dvc}
 */