Patches-1851591 ] dataview sample is crashing (under MSW)

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

diff --git a/docs/latex/wx/dataviewmodel.tex b/docs/latex/wx/dataviewmodel.tex
index 7ec14918d34226298f09f8cd213e440eb69160c8..7279f240e8ed9dbdea7781a7b0633ed0e68199de 100644 (file)
--- a/docs/latex/wx/dataviewmodel.tex
+++ b/docs/latex/wx/dataviewmodel.tex
@@ -3,13 +3,82 @@
 
 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.
+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
+\helpref{SetValue}{wxdataviewmodelsetvalue} which the
+wxDataViewCtrl will call when a change to some data has been
+commited.
+
+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.
+
+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}{wxdataviewmodelitemsadded},
+\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 
+\helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
+which link this class to the specific implementations on the
+supported platforms so that e.g. calling 
+\helpref{ValueChanged}{wxdataviewmodelvaluechanged}
+on this model will just call 
+\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 shared by several wxDataViewCtrls. 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 );
+    wxDataViewModel *musicModel = new MyMusicModel;
+    m_musicCtrl->AssociateModel( musicModel );
+    musicModel->DecRef();  // avoid memory leak !!
+    // add columns now
+\end{verbatim}
+}%

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -23,251 +92,220 @@ of the abstract wxDataViewModel.
 
 \helpref{wxAdv}{librarieslist}
 
 
 \helpref{wxAdv}{librarieslist}
 

+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+

 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
 
 \func{}{wxDataViewModel}{\void}
 
 Constructor.
 
 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
 
 \func{}{wxDataViewModel}{\void}
 
 Constructor.
 

+

 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
 
 \func{}{\destruct{wxDataViewModel}}{\void}
 
 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
 
 \func{}{\destruct{wxDataViewModel}}{\void}
 

-Destructor.
+Destructor. This should not be called directly. Use DecRef() instead.

 
 

-\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
-usually also allow the wxDataViewCtrl to change your data
-through its graphical interface, you will also have to override
-\helpref{SetValue}{wxdataviewlistmodelsetvalue} which the
-wxDataViewCtrl will call when a change to some data has been
-commited.
+\membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}

 
 

-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}.
+\func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}

 
 

+Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
+to the model.

 
 
 
 

-wxDataViewModel and this class (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.
+\membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}

 
 

-This class maintains a list of 
-\helpref{wxDataListViewListModelNotifier}{wxdataviewlistmodelnotifier}
-which link this class to the specific implementations on the
-supported platforms so that e.g. calling 
-\helpref{ValueChanged}{wxdataviewlistmodelvaluechanged}
-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.
+\func{virtual bool}{Cleared}{\void}

 
 

-\wxheading{Derived from}
+Called to inform the model that all data has been deleted.

 
 

-\helpref{wxDataViewModel}{wxdataviewmodel}\\
-\helpref{wxObjectRefData}{wxobjectrefdata}

 
 

-\wxheading{Include files}
+\membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}

 
 

-<wx/dataview.h>
+\func{virtual int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}

 
 

+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.

 
 

-\membersection{wxDataViewListModel::wxDataViewListModel}\label{wxdataviewlistmodelwxdataviewlistmodel}
+See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.

 
 

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

 
 

-Constructor.
+\membersection{wxDataViewModel::GetAttr}\label{wxdataviewmodelgetattr}
+
+\func{bool}{GetAttr}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}, \param{wxDataViewItemAttr\& }{attr}}

 
 

-\membersection{wxDataViewListModel::\destruct{wxDataViewListModel}}\label{wxdataviewlistmodeldtor}
+Oberride this to indicate that the item has special font attributes.
+This only affects the 
+\helpref{wxDataViewTextRendererText}{wxdataviewtextrendererattr} renderer.

 
 

-\func{}{\destruct{wxDataViewListModel}}{\void}
+See also \helpref{wxDataViewItemAttr}{wxdataviewitemattr}.

 
 

-Destructor.
+\membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}

 
 

-\membersection{wxDataViewListModel::AddNotifier}\label{wxdataviewlistmodeladdnotifier}
+\constfunc{virtual unsigned int}{GetColumnCount}{\void}

 
 

-\func{void}{AddNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
+Override this to indicate the number of columns in the model.

 
 

-Adds {\it notifier} to the internal list of notifers.

 
 

-See also \helpref{RemoveNotifier}{wxdataviewlistmodelremovenotifier}.
+\membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}

 
 

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

 
 

-\func{bool}{virtual Cleared}{\void}
+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}.

 
 

-Call this if all data in your model has been cleared.

 
 

-\membersection{wxDataViewListModel::GetColumnCount}\label{wxdataviewlistmodelgetcolumncount}
+\membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren}

 
 

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

 
 

-Override this to indicate, how many columns the list
-model has.
+Override this so the control can query the child items of
+an item. Returns the number of items.

 
 

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

 
 

-\func{virtual wxString}{GetColType}{\param{unsigned int }{col}}
+\membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}

 
 

-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}.
+\constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}

 
 

-\membersection{wxDataViewListModel::GetRowCount}\label{wxdataviewlistmodelgetrowcount}
+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.

 
 

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

 
 

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

 
 

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

 
 

-\func{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
+Override this to indicate the value of {\it item}
+A \helpref{wxVariant}{wxvariant} is used to store the data.

 
 

-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}

 
 

-\func{void}{RemoveNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
+\membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}

 
 

-Removes the notifier from the list of notifiers.
+\constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}}

 
 

-See also \helpref{AddNotifier}{wxdataviewlistmodeladdnotifier}.
+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::RowAppended}\label{wxdataviewlistmodelrowappended}

 
 

-\func{virtual bool}{RowAppended}{\void}
+\membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}

 
 

-Call this if a row has been appended to the list model.
+\constfunc{virtual bool}{HasDefaultCompare}{\void}

 
 

-\membersection{wxDataViewListModel::RowChanged}\label{wxdataviewlistmodelrowchanged}
+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.

 
 

-\func{virtual bool}{RowChanged}{\param{unsigned int }{row}}

 
 

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

 
 

-\membersection{wxDataViewListModel::RowDeleted}\label{wxdataviewlistmodelrowdeleted}
+\constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}

 
 

-\func{virtual bool}{RowDeleted}{\param{unsigned int }{row}}
+Override this to indicate of {\it item} is a container, i.e. if
+it can have child items.

 
 

-Call this if this row has been deleted.

 
 

-\membersection{wxDataViewListModel::RowInserted}\label{wxdataviewlistmodelrowinserted}
+\membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}

 
 

-\func{virtual bool}{RowInserted}{\param{unsigned int }{before}}
+\func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}

 
 

-Call this if a row has been inserted.
+Call this to inform the model that an item has been added
+to the data.

 
 

-\membersection{wxDataViewListModel::RowPrepended}\label{wxdataviewlistmodelrowprepended}

 
 

-\func{virtual bool}{RowPrepended}{\void}
+\membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}

 
 

-Call this if a row has been prepended.
+\func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}

 
 

-\membersection{wxDataViewListModel::RowsReordered}\label{wxdataviewlistmodelrowsreordered}
+Call this to inform the model that an item has changed.

 
 

-\func{virtual bool}{RowsReordered}{\param{unsigned int* }{new\_order}}
+This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
+event (in which the column fields will not be set) to the user. 

 
 

-Call this if the rows have been reorderd.

 
 

-\membersection{wxDataViewListModel::SetValue}\label{wxdataviewlistmodelsetvalue}
+\membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}

 
 

-\func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
+\func{virtual bool}{ItemDeleted}{\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 deleted from the data.

 
 
 
 

-\membersection{wxDataViewListModel::ValueChanged}\label{wxdataviewlistmodelvaluechanged}
+\membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}

 
 

-\func{virtual bool}{ValueChanged}{\param{unsigned int }{col}, \param{unsigned int }{row}}
+\func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}

 
 

-Call this if a value in the model has been changed.
+Call this to inform the model that several items have been added
+to the data.

 
 
 
 

-\section{\class{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodel}
+\membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}

 
 

-This class is used for sorting data. It does not contain any
-data itself. Rather, it provides a sorted interface for 
-another list model.
+\func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}}

 
 

-Currently, the sorting algorithm isn't thread safe. This needs
-to be fixed.
+Call this to inform the model that several items have changed.

 
 

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

 
 

-\helpref{wxDataViewListModel}{wxdataviewlistmodel}\\
-\helpref{wxDataViewModel}{wxdataviewmodel}\\
-\helpref{wxObjectRefData}{wxobjectrefdata}

 
 

-\wxheading{Include files}
+\membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}

 
 

-<wx/dataview.h>
+\func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
+
+Call this to inform the model that several items have been deleted.
+
+
+\membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}

 
 

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

 
 

-\func{}{wxDataViewSortedListModel}{\param{wxDataViewListModel* }{child}}
+Remove the {\it notifier} from the list of notifiers.

 
 

-Constructor. {\it child} is the child data model the data of
-which this model is supposed to present in a sorted way.

 
 

-\membersection{wxDataViewSortedListModel::\destruct{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodeldtor}
+\membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}

 
 

-\func{}{\destruct{wxDataViewSortedListModel}}{\void}
+\func{virtual void}{Resort}{\void}

 
 

-Destructor.
+Call this to initiate a resort after the sort function has
+been changed.

 
 

-\membersection{wxDataViewSortedListModel::GetAscending}\label{wxdataviewsortedlistmodelgetascending}

 
 

-\func{bool}{GetAscending}{\void}
+\membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}

 
 

-Returns true if the data is sorted in ascending order.
+\func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

 
 

-\membersection{wxDataViewSortedListModel::Resort}\label{wxdataviewsortedlistmodelresort}
+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!

 
 

-\func{void}{Resort}{\void}

 
 

-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.