take wxString, not wxChar* in wxStandardPaths::GetLocalizedResourcesDir

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

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

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.

\wxheading{Derived from}

\helpref{wxDataViewModel}{wxdataviewmodel}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>


\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::AddViewingColumn}\label{wxdataviewlistmodeladdviewingcolumn}

\func{void}{AddViewingColumn}{\param{wxDataViewColumn* }{view\_column}, \param{unsigned int }{model\_column}}

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

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

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

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

\func{virtual wxString}{GetColType}{\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{wxDataViewListModel::GetRowCount}\label{wxdataviewlistmodelgetrowcount}

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

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

\membersection{wxDataViewListModel::GetValue}\label{wxdataviewlistmodelgetvalue}

\func{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}

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

Removes the notifier from the list of notifiers.

See also \helpref{AddNotifier}{wxdataviewlistmodeladdnotifier}.

\membersection{wxDataViewListModel::RemoveViewingColumn}\label{wxdataviewlistmodelremoveviewingcolumn}

\func{void}{RemoveViewingColumn}{\param{wxDataViewColumn* }{column}}

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

\membersection{wxDataViewListModel::RowAppended}\label{wxdataviewlistmodelrowappended}

\func{virtual bool}{RowAppended}{\void}

Call this if a row has been appended to the list model.

\membersection{wxDataViewListModel::RowChanged}\label{wxdataviewlistmodelrowchanged}

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

Call this if the values of this row have been changed.

\membersection{wxDataViewListModel::RowDeleted}\label{wxdataviewlistmodelrowdeleted}

\func{virtual bool}{RowDeleted}{\param{unsigned int }{row}}

Call this if this row has been deleted.

\membersection{wxDataViewListModel::RowInserted}\label{wxdataviewlistmodelrowinserted}

\func{virtual bool}{RowInserted}{\param{unsigned int }{before}}

Call this if a row has been inserted.

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

\func{virtual bool}{RowPrepended}{\void}

Call this if a row has been prepended.

\membersection{wxDataViewListModel::RowsReordered}\label{wxdataviewlistmodelrowsreordered}

\func{virtual bool}{RowsReordered}{\param{unsigned int* }{new\_order}}

Call this if the rows have been reorderd.

\membersection{wxDataViewListModel::SetValue}\label{wxdataviewlistmodelsetvalue}

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

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.


\membersection{wxDataViewListModel::ValueChanged}\label{wxdataviewlistmodelvaluechanged}

\func{virtual bool}{ValueChanged}{\param{unsigned int }{col}, \param{unsigned int }{row}}

Call this if a value in the model has been changed.


\section{\class{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodel}

This class is used for sorting data. It does not contain any
data itself. Rather, it provides a sorted interface for 
another list model.

Currently, the sorting algorithm isn't thread safe. This needs
to be fixed.

\wxheading{Derived from}

\helpref{wxDataViewListModel}{wxdataviewlistmodel}\\
\helpref{wxDataViewModel}{wxdataviewmodel}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\membersection{wxDataViewSortedListModel::wxDataViewSortedListModel}\label{wxdataviewsortedlistmodelwxdataviewsortedlistmodel}

\func{}{wxDataViewSortedListModel}{\param{wxDataViewListModel* }{child}}

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}

\func{}{\destruct{wxDataViewSortedListModel}}{\void}

Destructor.

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

\func{bool}{GetAscending}{\void}

Returns true if the data is sorted in ascending order.

\membersection{wxDataViewSortedListModel::Resort}\label{wxdataviewsortedlistmodelresort}

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

Tell the model to resort its data.

\membersection{wxDataViewSortedListModel::SetAscending}\label{wxdataviewsortedlistmodelsetascending}

\func{void}{SetAscending}{\param{bool }{ascending}}

Set the sort order of the data.