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 095ce8918e7c3ece7a24e6ef067f9baf6a39f57e..4e56edd006459af61743c81981a8e09ae07e1ce5 100644 (file)
--- a/docs/latex/wx/dataviewmodel.tex
+++ b/docs/latex/wx/dataviewmodel.tex
@@ -3,283 +3,272 @@
 
 wxDataViewModel is the base class for all data model to be
 displayed by a \helpref{wxDataViewCtrl}{wxdataviewctrl}. 
 
 wxDataViewModel is the base class for all data model to be
 displayed by a \helpref{wxDataViewCtrl}{wxdataviewctrl}. 

-Currently, this class has no functionality at all and the
-only existing implementation of it is the 
-\helpref{wxDataViewListModel}{wxdataviewlistmodel}. The
-plan is to move all functionality of wxDataViewListModel
-and a to-be-written wxDataViewTreeModel into wxDataViewModel
-and make wxDataViewListModel and wxDataViewTreeModel subsets
-of the abstract wxDataViewModel.
-
-\wxheading{Derived from}
-
-\helpref{wxObjectRefData}{wxobjectrefdata}
-
-\wxheading{Include files}
-
-<wx/dataview.h>
-
-\membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
-
-\func{}{wxDataViewModel}{\void}
-
-Constructor.
-
-\membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
-
-\func{}{\destruct{wxDataViewModel}}{\void}
-
-Destructor.
-
-\section{\class{wxDataViewListModel}}\label{wxdataviewlistmodel}
-
-wxDataViewListModel is currently the only existing variant
-of a \helpref{wxDataViewModel}{wxdataviewmodel}. It allows
-to define a table like data model to be displayed by a
-\helpref{wxDataViewCtrl}{wxdataviewctrl}. You need to derive
-from this class to define your own data model.
-
-You need to override \helpref{GetRowCount}{wxdataviewlistmodelgetrowcount},
-\helpref{GetColumnCount}{wxdataviewlistmodelgetcolumncount},
-\helpref{GetColumnType}{wxdataviewlistmodelgetcolumntype} and
-\helpref{GetValue}{wxdataviewlistmodelgetvalue} in order to
-define the data model (which acts as an interface between 
-your actual data and the wxDataViewCtrl). Since you will
+All other models derive from it and must implement its
+pure virtual functions in order to define a complete
+data model. In detail, you need to override 
+\helpref{IsContainer}{wxdataviewmodeliscontainer},
+\helpref{GetParent}{wxdataviewmodelgetparent},
+\helpref{GetChildren}{wxdataviewmodelgetchildren},
+\helpref{GetColumnCount}{wxdataviewmodelgetcolumncount},
+\helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and
+\helpref{GetValue}{wxdataviewmodelgetvalue} 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
 usually also allow the wxDataViewCtrl to change your data
 through its graphical interface, you will also have to override

-\helpref{SetValue}{wxdataviewlistmodelsetvalue} which the
+\helpref{SetValue}{wxdataviewmodelsetvalue} which the

 wxDataViewCtrl will call when a change to some data has been
 commited.
 
 wxDataViewCtrl will call when a change to some data has been
 commited.
 

-The data that is presented through this data model is expected
-to change at run-time. You need to inform the data model that
-a change happens. Depending on what happened you need to call
-one of the following methods: 
-\helpref{ValueChanged}{wxdataviewlistmodelvaluechanged},
-\helpref{RowChanged}{wxdataviewlistmodelrowchanged},
-\helpref{RowAppended}{wxdataviewlistmodelrowappended},
-\helpref{RowPrepended}{wxdataviewlistmodelrowprepended},
-\helpref{RowInserted}{wxdataviewlistmodelrowinserted},
-\helpref{RowDeleted}{wxdataviewlistmodelrowdeleted},
-\helpref{RowsReordered}{wxdataviewlistmodelrowsreordered} or
-\helpref{RowsCleared}{wxdataviewlistmodelcleared}.
-
-
-
-wxDataViewModel and this class (as indeed the entire wxDataViewCtrl
+wxDataViewModel (as indeed the entire wxDataViewCtrl

 code) is using \helpref{wxVariant}{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.
 
 code) is using \helpref{wxVariant}{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.
 

+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. Depending on what happened you need to call
+one of the following methods: 
+\helpref{ValueChanged}{wxdataviewmodelvaluechanged},
+\helpref{ItemAdded}{wxdataviewmodelitemadded},
+\helpref{ItemDeleted}{wxdataviewmodelitemdeleted},
+\helpref{ItemChanged}{wxdataviewmodelitemchanged},
+\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 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}).
+

 This class maintains a list of 
 This class maintains a list of 

-\helpref{wxDataListViewListModelNotifier}{wxdataviewlistmodelnotifier}
+\helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}

 which link this class to the specific implementations on the
 supported platforms so that e.g. calling 
 which link this class to the specific implementations on the
 supported platforms so that e.g. calling 

-\helpref{ValueChanged}{wxdataviewlistmodelvaluechanged}
+\helpref{ValueChanged}{wxdataviewmodelvaluechanged}

 on this model will just call 
 on this model will just call 

-\helpref{wxDataListViewListModelNotifier::ValueChanged}{wxdataviewlistmodelnotifiervaluechanged}
-for each notifier that has been added. This is used both for
-informing the native controls to redraw themselves and for informing
-e.g. the \helpref{wxDataViewSortedListModel}{wxdataviewsortedlistmodel}
-to resort itself. You can also add your own notifier in order
-to get informed about any changes to the data in the list model.
-
-Additionally, this class maintains a list of all 
-\helpref{wxDataViewColumns}{wxdataviewcolumn} which
-display a certain column of this list model. This is
-mostly used internally.
+\helpref{wxDataViewModelNotifier::ValueChanged}{wxdataviewmodelnotifiervaluechanged}
+for each notifier that has been added. You can also add 
+your own notifier in order to get informed about any changes 
+to the data in the list model.
+
+Currently wxWidgets provides the following models apart
+from the base model: 
+\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}
 
 
 \wxheading{Derived from}
 

-\helpref{wxDataViewModel}{wxdataviewmodel}\\
-\helpref{wxObject}{wxobject}
+\helpref{wxObjectRefData}{wxobjectrefdata}

 
 \wxheading{Include files}
 
 <wx/dataview.h>
 
 
 \wxheading{Include files}
 
 <wx/dataview.h>
 

+\wxheading{Library}

 
 

-\membersection{wxDataViewListModel::wxDataViewListModel}\label{wxdataviewlistmodelwxdataviewlistmodel}
-
-\func{}{wxDataViewListModel}{\void}
-
-Constructor.
+\helpref{wxAdv}{librarieslist}

 
 

-\membersection{wxDataViewListModel::\destruct{wxDataViewListModel}}\label{wxdataviewlistmodeldtor}

 
 

-\func{}{\destruct{wxDataViewListModel}}{\void}

 
 

-Destructor.
+\latexignore{\rtfignore{\wxheading{Members}}}

 
 

-\membersection{wxDataViewListModel::AddNotifier}\label{wxdataviewlistmodeladdnotifier}
-
-\func{void}{AddNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
-
-Adds {\it notifier} to the internal list of notifers.
-
-See also \helpref{RemoveNotifier}{wxdataviewlistmodelremovenotifier}.
-
-\membersection{wxDataViewListModel::AddViewingColumn}\label{wxdataviewlistmodeladdviewingcolumn}
-
-\func{void}{AddViewingColumn}{\param{wxDataViewColumn* }{view\_column}, \param{unsigned int }{model\_column}}
+\membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}

 
 

-Used internally. Used for maintaining a list of
-\helpref{wxDataViewColumn}{wxdataviewcolumn} that
-display a certain column of this model.
+\func{}{wxDataViewModel}{\void}

 
 

-\membersection{wxDataViewListModel::Cleared}\label{wxdataviewlistmodelcleared}
+Constructor.

 
 

-\func{bool}{virtual Cleared}{\void}
+\membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}

 
 

-Call this if all data in your model has been cleared.
+\func{}{\destruct{wxDataViewModel}}{\void}

 
 

-\membersection{wxDataViewListModel::GetColumnCount}\label{wxdataviewlistmodelgetcolumncount}
+Destructor. This should not be called directly. Use DecRef() instead.

 
 

-\func{virtual unsigned int}{GetColumnCount}{\void}

 
 

-Override this to indicate, how many columns the list
-model has.
+\membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}

 
 

-\membersection{wxDataViewListModel::GetColumnType}\label{wxdataviewlistmodelgetcolumntype}
+\func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}

 
 

-\func{virtual wxString}{GetColType}{\param{unsigned int }{col}}
+Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
+to the model.

 
 

-Override this to indicate what type of data is stored in the
-column specified by {\it col}. This should return a string
-indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
+\membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}

 
 

-\membersection{wxDataViewListModel::GetRowCount}\label{wxdataviewlistmodelgetrowcount}
+\func{virtual bool}{Cleared}{\void}

 
 

-\func{virtual unsigned int}{GetRowCount}{\void}
+Called to inform the model that all data has been deleted.

 
 

-Override this to indicate, how many rows the list
-model has.
+\membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}

 
 

-\membersection{wxDataViewListModel::GetValue}\label{wxdataviewlistmodelgetvalue}
+\func{virtual int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}

 
 

-\func{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
+The compare function to be used by control. The default compare function
+sorts by container and other items separately and in ascending order.
+Override this for a different sorting behaviour.

 
 

-Override this to indicate the value of a given value
-in the list model. A \helpref{wxVariant}{wxvariant}
-is used to store the data.
+See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.

 
 

-\membersection{wxDataViewListModel::RemoveNotifier}\label{wxdataviewlistmodelremovenotifier}
+\membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}

 
 

-\func{void}{RemoveNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
+\constfunc{virtual unsigned int}{GetColumnCount}{\void}

 
 

-Removes the notifier from the list of notifiers.
+Override this to indicate the number of columns in the model.

 
 

-See also \helpref{AddNotifier}{wxdataviewlistmodeladdnotifier}.
+\membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}

 
 

-\membersection{wxDataViewListModel::RemoveViewingColumn}\label{wxdataviewlistmodelremoveviewingcolumn}
+\constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}

 
 

-\func{void}{RemoveViewingColumn}{\param{wxDataViewColumn* }{column}}
+Override this to indicate what type of data is stored in the
+column specified by {\it col}. This should return a string
+indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.

 
 

-Used internally. Used for maintaining a list of
-\helpref{wxDataViewColumn}{wxdataviewcolumn} that
-display a certain column of this model.
+\membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren}

 
 

-\membersection{wxDataViewListModel::RowAppended}\label{wxdataviewlistmodelrowappended}
+\constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }

 
 

-\func{virtual bool}{RowAppended}{\void}
+Override this so the control can query the child items of
+an item. Returns the number of items.

 
 

-Call this if a row has been appended to the list model.
+\membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}

 
 

-\membersection{wxDataViewListModel::RowChanged}\label{wxdataviewlistmodelrowchanged}
+\constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}

 
 

-\func{virtual bool}{RowChanged}{\param{unsigned int }{row}}
+Override this to indicate which wxDataViewItem representing the parent
+of {\it item} or an invalid wxDataViewItem if the the root item is
+the parent item.

 
 

-Call this if the values of this row have been changed.
+\membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}

 
 

-\membersection{wxDataViewListModel::RowDeleted}\label{wxdataviewlistmodelrowdeleted}
+\constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

 
 

-\func{virtual bool}{RowDeleted}{\param{unsigned int }{row}}
+Override this to indicate the value of {\it item}
+A \helpref{wxVariant}{wxvariant} is used to store the data.

 
 

-Call this if this row has been deleted.

 
 

-\membersection{wxDataViewListModel::RowInserted}\label{wxdataviewlistmodelrowinserted}
+\membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}

 
 

-\func{virtual bool}{RowInserted}{\param{unsigned int }{before}}
+\constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}}

 
 

-Call this if a row has been inserted.
+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{wxDataViewListModel::RowPrepended}\label{wxdataviewlistmodelrowprepended}
+\membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}

 
 

-\func{virtual bool}{RowPrepended}{\void}
+\constfunc{virtual bool}{HasDefaultCompare}{\void}

 
 

-Call this if a row has been prepended.
+Override this to indicate that the model provides a default compare
+function that the control should use if no wxDataViewColumn has been
+chosen for sorting. Usually, the user clicks on a column header for
+sorting, the data will be sorted alphanumerically. If any other
+order (e.g. by index or order of appearance) is required, then this
+should be used. See also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
+for a model which makes use of this.

 
 

-\membersection{wxDataViewListModel::RowsReordered}\label{wxdataviewlistmodelrowsreordered}
+\membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}

 
 

-\func{virtual bool}{RowsReordered}{\param{unsigned int* }{new\_order}}
+\constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}

 
 

-Call this if the rows have been reorderd.
+Override this to indicate of {\it item} is a container, i.e. if
+it can have child items.

 
 

-\membersection{wxDataViewListModel::SetValue}\label{wxdataviewlistmodelsetvalue}
+\membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}

 
 

-\func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
+\func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}

 
 

-This method gets called by e.g. the wxDataViewCtrl class if a 
-value has been changed through its graphical interface. You
-need to override this method in order to update the data in
-the underlying data structur. Afterwards, 
-\helpref{ValueChanged}{wxdataviewlistmodelvaluechanged} is called.
+Call this to inform the model that an item has been added
+to the data.

 
 

+\membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}

 
 

-\membersection{wxDataViewListModel::ValueChanged}\label{wxdataviewlistmodelvaluechanged}
+\func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}

 
 

-\func{virtual bool}{ValueChanged}{\param{unsigned int }{col}, \param{unsigned int }{row}}
+Call this to inform the model that an item has changed.

 
 

-Call this if a value in the model has been 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}

 
 

-\section{\class{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodel}
+\func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}

 
 

-This class is used for sorting data. It does not contain any
-data itself. Rather, it provides a sorted interface for 
-another list model.
+Call this to inform the model that several items have been added
+to the data.

 
 

-Currently, the sorting algorithm isn't thread safe. This needs
-to be fixed.
+\membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}

 
 

-\wxheading{Derived from}
+\func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}}

 
 

-\helpref{wxDataViewListModel}{wxdataviewlistmodel}\\
-\helpref{wxDataViewModel}{wxdataviewmodel}\\
-\helpref{wxObject}{wxobject}
+Call this to inform the model that several items have changed.

 
 

-\wxheading{Include files}
+This will eventually emit wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
+events (in which the column fields will not be set) to the user. 

 
 

-<wx/dataview.h>
+\membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}

 
 

-\membersection{wxDataViewSortedListModel::wxDataViewSortedListModel}\label{wxdataviewsortedlistmodelwxdataviewsortedlistmodel}
+\func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}

 
 

-\func{}{wxDataViewSortedListModel}{\param{wxDataViewListModel* }{child}}
+Call this to inform the model that several items have been deleted.

 
 

-Constructor. {\it child} is the child data model the data of
-which this model is supposed to present in a sorted way.
+\membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}

 
 

-\membersection{wxDataViewSortedListModel::\destruct{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodeldtor}
+\func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}

 
 

-\func{}{\destruct{wxDataViewSortedListModel}}{\void}
+Remove the {\it notifier} from the list of notifiers.

 
 

-Destructor.
+\membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}

 
 

-\membersection{wxDataViewSortedListModel::GetAscending}\label{wxdataviewsortedlistmodelgetascending}
+\func{virtual void}{Resort}{\void}

 
 

-\func{bool}{GetAscending}{\void}
+Call this to initiate a resort after the sort function has
+been changed.

 
 

-Returns true if the data is sorted in ascending order.
+\membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}

 
 

-\membersection{wxDataViewSortedListModel::Resort}\label{wxdataviewsortedlistmodelresort}
+\func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

 
 

-\func{void}{Resort}{\void}
+This gets called in order to set a value in the data model.
+The most common scenario is that the wxDataViewCtrl calls
+this method after the user changed some data in the view.
+Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
+has to be called!

 
 

-Tell the model to resort its data.
+\membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}

 
 

-\membersection{wxDataViewSortedListModel::SetAscending}\label{wxdataviewsortedlistmodelsetascending}
+\func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

 
 

-\func{void}{SetAscending}{\param{bool }{ascending}}
+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.

 
 

-Set the sort order of the data.
+This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
+event to the user.