Applied patch [ 1747059 ] wxAUIDefaultTabArt wxAUI_NB_BOTTOM

[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{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}{wxdataviewlistmodelsetvalue} 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}.

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.

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}. 
It is planned to add helper classes for simple tree
and list stores in the future.

\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. This should not be called directly. Use DecRef() instead.


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

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

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

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

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

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

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

\func{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{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}

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

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

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

\constfunc{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::GetFirstChild}\label{wxdataviewmodelgetfirstchild}

\constfunc{wxDataViewItem}{GetFirstChild}{\param{const wxDataViewItem\& }{parent}}

To be removed.

\membersection{wxDataViewModel::GetNextSibling}\label{wxdataviewmodelgetnextsibling}

\constfunc{wxDataViewItem}{GetNextSibling}{\param{const wxDataViewItem\& }{item}}

To be removed.

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

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

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

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

\constfunc{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{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{bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}

Call this to inform the model that an item has changed.

\membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}

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

Call this to inform the model that an item has 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{void}{Resort}{\void}

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

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

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