Updated docs
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@48231 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Robert Roebling
@@ -3,13 +3,59 @@
|
||||
|
||||
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{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}
|
||||
|
||||
@@ -29,245 +75,128 @@ of the abstract wxDataViewModel.
|
||||
|
||||
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}.
|
||||
Destructor. This should not be called directly. Use DecRef() instead.
|
||||
|
||||
|
||||
\membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
|
||||
|
||||
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.
|
||||
\func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
|
||||
|
||||
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.
|
||||
Adds a \helpref{wxDataViewModelNotifier}{wxdataviewlistmodelnotifier}
|
||||
to the 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.
|
||||
\membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
|
||||
|
||||
\wxheading{Derived from}
|
||||
\func{bool}{Cleared}{\void}
|
||||
|
||||
\helpref{wxDataViewModel}{wxdataviewmodel}\\
|
||||
\helpref{wxObjectRefData}{wxobjectrefdata}
|
||||
Called to inform the model that all data has been deleted.
|
||||
|
||||
\wxheading{Include files}
|
||||
\membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
|
||||
|
||||
<wx/dataview.h>
|
||||
\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{wxDataViewListModel::wxDataViewListModel}\label{wxdataviewlistmodelwxdataviewlistmodel}
|
||||
\membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
|
||||
|
||||
\func{}{wxDataViewListModel}{\void}
|
||||
\constfunc{unsigned int}{GetColumnCount}{\void}
|
||||
|
||||
Constructor.
|
||||
Override this to indicate the number of columns in the model.
|
||||
|
||||
\membersection{wxDataViewListModel::\destruct{wxDataViewListModel}}\label{wxdataviewlistmodeldtor}
|
||||
\membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
|
||||
|
||||
\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}
|
||||
|
||||
Override this to indicate, how many columns the list
|
||||
model has.
|
||||
|
||||
\membersection{wxDataViewListModel::GetColumnType}\label{wxdataviewlistmodelgetcolumntype}
|
||||
|
||||
\func{virtual wxString}{GetColType}{\param{unsigned int }{col}}
|
||||
\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{wxDataViewListModel::GetRowCount}\label{wxdataviewlistmodelgetrowcount}
|
||||
\membersection{wxDataViewModel::GetFirstChild}\label{wxdataviewmodelgetfirstchild}
|
||||
|
||||
\func{virtual unsigned int}{GetRowCount}{\void}
|
||||
\constfunc{wxDataViewItem}{GetFirstChild}{\param{const wxDataViewItem\& }{parent}}
|
||||
|
||||
Override this to indicate, how many rows the list
|
||||
model has.
|
||||
To be removed.
|
||||
|
||||
\membersection{wxDataViewListModel::GetValue}\label{wxdataviewlistmodelgetvalue}
|
||||
\membersection{wxDataViewModel::GetNextSibling}\label{wxdataviewmodelgetnextsibling}
|
||||
|
||||
\func{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
|
||||
\constfunc{wxDataViewItem}{GetNextSibling}{\param{const wxDataViewItem\& }{item}}
|
||||
|
||||
Override this to indicate the value of a given value
|
||||
in the list model. A \helpref{wxVariant}{wxvariant}
|
||||
is used to store the data.
|
||||
To be removed.
|
||||
|
||||
\membersection{wxDataViewListModel::RemoveNotifier}\label{wxdataviewlistmodelremovenotifier}
|
||||
\membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
|
||||
|
||||
\func{void}{RemoveNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
|
||||
\constfunc{wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
|
||||
|
||||
Removes the notifier from the list of notifiers.
|
||||
Override this to indicate which wxDataViewItem representing the parent
|
||||
of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
|
||||
|
||||
See also \helpref{AddNotifier}{wxdataviewlistmodeladdnotifier}.
|
||||
\membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
|
||||
|
||||
\membersection{wxDataViewListModel::RowAppended}\label{wxdataviewlistmodelrowappended}
|
||||
\constfunc{void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
|
||||
|
||||
\func{virtual bool}{RowAppended}{\void}
|
||||
Override this to indicate the value of {\it item}
|
||||
A \helpref{wxVariant}{wxvariant} is used to store the data.
|
||||
|
||||
Call this if a row has been appended to the list model.
|
||||
\membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
|
||||
|
||||
\membersection{wxDataViewListModel::RowChanged}\label{wxdataviewlistmodelrowchanged}
|
||||
\constfunc{bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
|
||||
|
||||
\func{virtual bool}{RowChanged}{\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 the values of this row have been changed.
|
||||
\membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
|
||||
|
||||
\membersection{wxDataViewListModel::RowDeleted}\label{wxdataviewlistmodelrowdeleted}
|
||||
\func{bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
|
||||
|
||||
\func{virtual bool}{RowDeleted}{\param{unsigned int }{row}}
|
||||
Call this to inform the model that an item has been added
|
||||
to the data.
|
||||
|
||||
Call this if this row has been deleted.
|
||||
\membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
|
||||
|
||||
\membersection{wxDataViewListModel::RowInserted}\label{wxdataviewlistmodelrowinserted}
|
||||
\func{bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
|
||||
|
||||
\func{virtual bool}{RowInserted}{\param{unsigned int }{before}}
|
||||
Call this to inform the model that an item has changed.
|
||||
|
||||
Call this if a row has been inserted.
|
||||
\membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
|
||||
|
||||
\membersection{wxDataViewListModel::RowPrepended}\label{wxdataviewlistmodelrowprepended}
|
||||
\func{bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
|
||||
|
||||
\func{virtual bool}{RowPrepended}{\void}
|
||||
Call this to inform the model that an item has been deleted.
|
||||
|
||||
Call this if a row has been prepended.
|
||||
\membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
|
||||
|
||||
\membersection{wxDataViewListModel::RowsReordered}\label{wxdataviewlistmodelrowsreordered}
|
||||
\func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
|
||||
|
||||
\func{virtual bool}{RowsReordered}{\param{unsigned int* }{new\_order}}
|
||||
Remove the {\it notifier} from the list of notifiers.
|
||||
|
||||
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{wxObjectRefData}{wxobjectrefdata}
|
||||
|
||||
\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}
|
||||
\membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
|
||||
|
||||
\func{void}{Resort}{\void}
|
||||
|
||||
Tell the model to resort its data.
|
||||
Call this to initiate a resort after the sort function has
|
||||
been changed.
|
||||
|
||||
\membersection{wxDataViewSortedListModel::SetAscending}\label{wxdataviewsortedlistmodelsetascending}
|
||||
\membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
|
||||
|
||||
\func{void}{SetAscending}{\param{bool }{ascending}}
|
||||
\func{bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
|
||||
|
||||
Set the sort order of the 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{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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user