API change: a single SELECTION_CHANGED not lots of SELECT and UNSELECT events

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

diff --git a/docs/latex/wx/dataviewmodel.tex b/docs/latex/wx/dataviewmodel.tex
index a6aea2285110da3d52dd839c65e9af6a8dec5e24..b80c86fe7a605fe92161e6b3ecad54362f11c03d 100644 (file)
--- a/docs/latex/wx/dataviewmodel.tex
+++ b/docs/latex/wx/dataviewmodel.tex
@@ -3,271 +3,215 @@
 
 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>
-
-\wxheading{Library}
-
-\helpref{wxAdv}{librarieslist}
-
-\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}.
+
+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
+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}. 
+It is planned to add helper classes for simple tree
+and list stores in the future.

 
 \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.
-
-\membersection{wxDataViewListModel::\destruct{wxDataViewListModel}}\label{wxdataviewlistmodeldtor}
-
-\func{}{\destruct{wxDataViewListModel}}{\void}
-
-Destructor.
-
-\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::Cleared}\label{wxdataviewlistmodelcleared}
-
-\func{bool}{virtual Cleared}{\void}
-
-Call this if all data in your model has been cleared.
-
-\membersection{wxDataViewListModel::GetColumnCount}\label{wxdataviewlistmodelgetcolumncount}
-
-\func{virtual unsigned int}{GetColumnCount}{\void}
+\helpref{wxAdv}{librarieslist}

 
 

-Override this to indicate, how many columns the list
-model has.

 
 

-\membersection{wxDataViewListModel::GetColumnType}\label{wxdataviewlistmodelgetcolumntype}

 
 

-\func{virtual wxString}{GetColType}{\param{unsigned int }{col}}
+\latexignore{\rtfignore{\wxheading{Members}}}

 
 

-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::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}

 
 

-\membersection{wxDataViewListModel::GetRowCount}\label{wxdataviewlistmodelgetrowcount}
+\func{}{wxDataViewModel}{\void}

 
 

-\func{virtual unsigned int}{GetRowCount}{\void}
+Constructor.

 
 

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

 
 

-\membersection{wxDataViewListModel::GetValue}\label{wxdataviewlistmodelgetvalue}
+\func{}{\destruct{wxDataViewModel}}{\void}

 
 

-\func{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
+Destructor. This should not be called directly. Use DecRef() instead.

 
 

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

 
 

-\membersection{wxDataViewListModel::RemoveNotifier}\label{wxdataviewlistmodelremovenotifier}
+\membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}

 
 

-\func{void}{RemoveNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
+\func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}

 
 

-Removes the notifier from the list of notifiers.
+Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
+to the model.

 
 

-See also \helpref{AddNotifier}{wxdataviewlistmodeladdnotifier}.
+\membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}

 
 

-\membersection{wxDataViewListModel::RowAppended}\label{wxdataviewlistmodelrowappended}
+\func{virtual bool}{Cleared}{\void}

 
 

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

 
 

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

 
 

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

 
 

-\func{virtual bool}{RowChanged}{\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.

 
 

-Call this if the values of this row have been changed.
+See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.

 
 

-\membersection{wxDataViewListModel::RowDeleted}\label{wxdataviewlistmodelrowdeleted}
+\membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}

 
 

-\func{virtual bool}{RowDeleted}{\param{unsigned int }{row}}
+\constfunc{virtual unsigned int}{GetColumnCount}{\void}

 
 

-Call this if this row has been deleted.
+Override this to indicate the number of columns in the model.

 
 

-\membersection{wxDataViewListModel::RowInserted}\label{wxdataviewlistmodelrowinserted}
+\membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}

 
 

-\func{virtual bool}{RowInserted}{\param{unsigned int }{before}}
+\constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}

 
 

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

 
 

-\func{virtual bool}{RowPrepended}{\void}
+\constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }

 
 

-Call this if a row has been prepended.
+Override this so the control can query the child items of
+an item. Returns the number of items.

 
 

-\membersection{wxDataViewListModel::RowsReordered}\label{wxdataviewlistmodelrowsreordered}
+\membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}

 
 

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

 
 

-Call this if the rows have been reorderd.
+Override this to indicate which wxDataViewItem representing the parent
+of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.

 
 

-\membersection{wxDataViewListModel::SetValue}\label{wxdataviewlistmodelsetvalue}
+\membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}

 
 

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

 
 

-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.
+Override this to indicate the value of {\it item}
+A \helpref{wxVariant}{wxvariant} is used to store the data.

 
 

+\membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}

 
 

-\membersection{wxDataViewListModel::ValueChanged}\label{wxdataviewlistmodelvaluechanged}
+\constfunc{virtual bool}{HasDefaultCompare}{\void}

 
 

-\func{virtual bool}{ValueChanged}{\param{unsigned int }{col}, \param{unsigned int }{row}}
+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.

 
 

-Call this if a value in the model has been changed.
+\membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}

 
 

+\constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}

 
 

-\section{\class{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodel}
+Override this to indicate of {\it item} is a container, i.e. if
+it can have child 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.
+\membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}

 
 

-Currently, the sorting algorithm isn't thread safe. This needs
-to be fixed.
+\func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}

 
 

-\wxheading{Derived from}
+Call this to inform the model that an item has been added
+to the data.

 
 

-\helpref{wxDataViewListModel}{wxdataviewlistmodel}\\
-\helpref{wxDataViewModel}{wxdataviewmodel}\\
-\helpref{wxObject}{wxobject}
+\membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}

 
 

-\wxheading{Include files}
+\func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}

 
 

-<wx/dataview.h>
+Call this to inform the model that an item has changed.

 
 

-\membersection{wxDataViewSortedListModel::wxDataViewSortedListModel}\label{wxdataviewsortedlistmodelwxdataviewsortedlistmodel}
+\membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}

 
 

-\func{}{wxDataViewSortedListModel}{\param{wxDataViewListModel* }{child}}
+\func{virtual bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}

 
 

-Constructor. {\it child} is the child data model the data of
-which this model is supposed to present in a sorted way.
+Call this to inform the model that an item has been deleted.

 
 

-\membersection{wxDataViewSortedListModel::\destruct{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodeldtor}
+\membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}

 
 

-\func{}{\destruct{wxDataViewSortedListModel}}{\void}
+\func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}

 
 

-Destructor.
+Remove the {\it notifier} from the list of notifiers.

 
 

-\membersection{wxDataViewSortedListModel::GetAscending}\label{wxdataviewsortedlistmodelgetascending}
+\membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}

 
 

-\func{bool}{GetAscending}{\void}
+\func{virtual void}{Resort}{\void}

 
 

-Returns true if the data is sorted in ascending order.
+Call this to initiate a resort after the sort function has
+been changed.

 
 

-\membersection{wxDataViewSortedListModel::Resort}\label{wxdataviewsortedlistmodelresort}
+\membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}

 
 

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

 
 

-Tell the model to resort its data.
+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!

 
 

-\membersection{wxDataViewSortedListModel::SetAscending}\label{wxdataviewsortedlistmodelsetascending}
+\membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}

 
 

-\func{void}{SetAscending}{\param{bool }{ascending}}
+\func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

 
 

-Set the sort order of the data.
+Call this to inform this model that a value in
+the model has been changed.