remove C++ comment

[wxWidgets.git] / docs / latex / wx / dataviewmodel.tex

diff --git a/docs/latex/wx/dataviewmodel.tex b/docs/latex/wx/dataviewmodel.tex
index 92624d850104e25b6259c91f304c1adcdaf99813..4e56edd006459af61743c81981a8e09ae07e1ce5 100644 (file)
--- a/docs/latex/wx/dataviewmodel.tex
+++ b/docs/latex/wx/dataviewmodel.tex
@@ -33,15 +33,20 @@ one of the following methods:
 \helpref{ItemAdded}{wxdataviewmodelitemadded},
 \helpref{ItemDeleted}{wxdataviewmodelitemdeleted},
 \helpref{ItemChanged}{wxdataviewmodelitemchanged},
-\helpref{Cleared}{wxdataviewmodelcleared}.
+\helpref{Cleared}{wxdataviewmodelcleared}. There are
+plural forms for notification of addition, change
+or removal of several item at once. See 
+\helpref{ItemsAdded}{wxdataviewmodelitesmadded},
+\helpref{ItemsDeleted}{wxdataviewmodelitemsdeleted},
+\helpref{ItemsChanged}{wxdataviewmodelitemschanged},
 
 Note that wxDataViewModel does not define the position or
-index of any item in the control since several control might
-display the data differently, but wxDataViewModel does
+index of any item in the control because different controls
+might display the same data differently. wxDataViewModel does
 provide a \helpref{Compare}{wxdataviewmodelcompare} method
 which the wxDataViewCtrl may use to sort the data either
 in conjunction with a column header or without (see
-\helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
+\helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}).
 
 This class maintains a list of 
 \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
@@ -56,9 +61,26 @@ to the data in the list model.
 
 Currently wxWidgets provides the following models apart
 from the base model: 
-\helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}. 
-It is planned to add helper classes for simple tree
-and list stores in the future.
+\helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel},
+\helpref{wxDataViewTreeStore}{wxdataviewtreestore}.
+
+Note that wxDataViewModel is reference counted, derives from 
+\helpref{wxObjectRefData}{wxobjectrefdata} and cannot be deleted
+directly as it can be shares by several wxDataViewCtrl. This
+implies that you need to decrease the reference count after
+associating the model with a control like this:
+
+{\small%
+\begin{verbatim}
+    wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL, wxDefaultPosition,
+                                                     wxDefaultSize, wxDV_MULTIPLE );
+    wxDataViewModel *musicModel = new MyMusicModel;
+    m_musicCtrl->AssociateModel( musicModel );
+    musicModel->DecRef();  // avoid memory leak !!
+
+    // add columns now
+\end{verbatim}
+}%
 
 \wxheading{Derived from}
 
@@ -138,7 +160,8 @@ an item. Returns the number of items.
 \constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 
 Override this to indicate which wxDataViewItem representing the parent
-of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
+of {\it item} or an invalid wxDataViewItem if the the root item is
+the parent item.
 
 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 
@@ -147,6 +170,16 @@ of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
 Override this to indicate the value of {\it item}
 A \helpref{wxVariant}{wxvariant} is used to store the data.
 
+
+\membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}
+
+\constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}}
+
+Override this method to indicate if a container item merely
+acts as a headline (or for categorisation) or if it also
+acts a normal item with entries for futher columns. By 
+default returns {\it false}.
+
 \membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
 
 \constfunc{virtual bool}{HasDefaultCompare}{\void}
@@ -179,6 +212,9 @@ to the data.
 
 Call this to inform the model that an item has changed.
 
+This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
+event (in which the column fields will not be set) to the user. 
+
 \membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}
 
 \func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
@@ -192,6 +228,9 @@ to the data.
 
 Call this to inform the model that several items have changed.
 
+This will eventually emit wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
+events (in which the column fields will not be set) to the user. 
+
 \membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}
 
 \func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
@@ -225,6 +264,11 @@ has to be called!
 
 \func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 
-Call this to inform this model that a value in
-the model has been changed.
+Call this to inform this model that a value in the model has
+been changed. This is also called from wxDataViewCtrl's
+internal editing code, e.g. when editing a text field 
+in the control.
+
+This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
+event to the user.