added null pointer check and assert

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

\section{\class{wxDataViewModel}}\label{wxdataviewmodel}

wxDataViewModel is the base class for all data model to be
displayed by a \helpref{wxDataViewCtrl}{wxdataviewctrl}. 
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}

\helpref{wxObjectRefData}{wxobjectrefdata}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}



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


\membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}

\func{}{wxDataViewModel}{\void}

Constructor.


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

\func{}{\destruct{wxDataViewModel}}{\void}

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



\membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}

\func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}

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


\membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}

\func{virtual bool}{Cleared}{\void}

Called to inform the model that all data has been deleted.


\membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}

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

See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.


\membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}

\constfunc{virtual unsigned int}{GetColumnCount}{\void}

Override this to indicate the number of columns in the model.


\membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}

\constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}

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::GetChildren}\label{wxdataviewmodelgetchildren}

\constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }

Override this so the control can query the child items of
an item. Returns the number of items.


\membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}

\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 the the root item is
the parent item.


\membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}

\constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

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}

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

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

Override this to indicate of {\it item} is a container, i.e. if
it can have child items.


\membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}

\func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}

Call this to inform the model that an item has been added
to the data.


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

\func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}

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::ItemDeleted}\label{wxdataviewmodelitemdeleted}

\func{virtual bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}

Call this to inform the model that an item has been deleted from the data.


\membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}

\func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}

Call this to inform the model that several items have been added
to the data.


\membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}

\func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}}

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

Call this to inform the model that several items have been deleted.


\membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}

\func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}

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


\membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}

\func{virtual void}{Resort}{\void}

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


\membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}

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

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

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