docs/latex/wx/dataviewmodel.tex

   1
   2 \section{\class{wxDataViewModel}}\label{wxdataviewmodel}
   3
   4 wxDataViewModel is the base class for all data model to be
   5 displayed by a \helpref{wxDataViewCtrl}{wxdataviewctrl}.
   6 All other models derive from it and must implement its
   7 pure virtual functions in order to define a complete
   8 data model. In detail, you need to override
   9 \helpref{IsContainer}{wxdataviewmodeliscontainer},
  10 \helpref{GetParent}{wxdataviewmodelgetparent},
  11 \helpref{GetColumnCount}{wxdataviewmodelgetcolumncount},
  12 \helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and
  13 \helpref{GetValue}{wxdataviewmodelgetvalue} in order to
  14 define the data model which acts as an interface between
  15 your actual data and the wxDataViewCtrl. Since you will
  16 usually also allow the wxDataViewCtrl to change your data
  17 through its graphical interface, you will also have to override
  18 \helpref{SetValue}{wxdataviewmodelsetvalue} which the
  19 wxDataViewCtrl will call when a change to some data has been
  20 commited.
  21
  22 wxDataViewModel (as indeed the entire wxDataViewCtrl
  23 code) is using \helpref{wxVariant}{wxvariant} to store data and
  24 its type in a generic way. wxVariant can be extended to contain
  25 almost any data without changes to the original class.
  26
  27 The data that is presented through this data model is expected
  28 to change at run-time. You need to inform the data model when
  29 a change happened. Depending on what happened you need to call
  30 one of the following methods:
  31 \helpref{ValueChanged}{wxdataviewmodelvaluechanged},
  32 \helpref{ItemAdded}{wxdataviewmodelitemadded},
  33 \helpref{ItemDeleted}{wxdataviewmodelitemdeleted},
  34 \helpref{ItemChanged}{wxdataviewmodelitemchanged},
  35 \helpref{Cleared}{wxdataviewmodelcleared}.
  36
  37 Note that wxDataViewModel does not define the position or
  38 index of any item in the control since several control might
  39 display the data differently, but wxDataViewModel does
  40 provide a \helpref{Compare}{wxdataviewmodelcompare} method
  41 which the wxDataViewCtrl may use to sort the data either
  42 in conjunction with a column header or without (see
  43 \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
  44
  45 This class maintains a list of
  46 \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
  47 which link this class to the specific implementations on the
  48 supported platforms so that e.g. calling
  49 \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
  50 on this model will just call
  51 \helpref{wxDataViewModelNotifier::ValueChanged}{wxdataviewmodelnotifiervaluechanged}
  52 for each notifier that has been added. You can also add
  53 your own notifier in order to get informed about any changes
  54 to the data in the list model.
  55
  56 Currently wxWidgets provides the following models apart
  57 from the base model:
  58 \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}.
  59 It is planned to add helper classes for simple tree
  60 and list stores in the future.
  61
  62 \wxheading{Derived from}
  63
  64 \helpref{wxObjectRefData}{wxobjectrefdata}
  65
  66 \wxheading{Include files}
  67
  68 <wx/dataview.h>
  69
  70 \wxheading{Library}
  71
  72 \helpref{wxAdv}{librarieslist}
  73
  74
  75
  76 \latexignore{\rtfignore{\wxheading{Members}}}
  77
  78 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
  79
  80 \func{}{wxDataViewModel}{\void}
  81
  82 Constructor.
  83
  84 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
  85
  86 \func{}{\destruct{wxDataViewModel}}{\void}
  87
  88 Destructor. This should not be called directly. Use DecRef() instead.
  89
  90
  91 \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
  92
  93 \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
  94
  95 Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
  96 to the model.
  97
  98 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
  99
 100 \func{bool}{Cleared}{\void}
 101
 102 Called to inform the model that all data has been deleted.
 103
 104 \membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
 105
 106 \func{int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}
 107
 108 The compare function to be used by control. The default compare function
 109 sorts by container and other items separately and in ascending order.
 110 Override this for a different sorting behaviour.
 111
 112 See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
 113
 114 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 115
 116 \constfunc{unsigned int}{GetColumnCount}{\void}
 117
 118 Override this to indicate the number of columns in the model.
 119
 120 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 121
 122 \constfunc{wxString}{GetColumnType}{\param{unsigned int }{col}}
 123
 124 Override this to indicate what type of data is stored in the
 125 column specified by {\it col}. This should return a string
 126 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 127
 128 \membersection{wxDataViewModel::GetFirstChild}\label{wxdataviewmodelgetfirstchild}
 129
 130 \constfunc{wxDataViewItem}{GetFirstChild}{\param{const wxDataViewItem\& }{parent}}
 131
 132 To be removed.
 133
 134 \membersection{wxDataViewModel::GetNextSibling}\label{wxdataviewmodelgetnextsibling}
 135
 136 \constfunc{wxDataViewItem}{GetNextSibling}{\param{const wxDataViewItem\& }{item}}
 137
 138 To be removed.
 139
 140 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 141
 142 \constfunc{wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 143
 144 Override this to indicate which wxDataViewItem representing the parent
 145 of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
 146
 147 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 148
 149 \constfunc{void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 150
 151 Override this to indicate the value of {\it item}
 152 A \helpref{wxVariant}{wxvariant} is used to store the data.
 153
 154 \membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
 155
 156 \func{bool}{HasDefaultCompare}{\void}
 157
 158 Override this to indicate that the model provides a default compare
 159 function that the control should use if no wxDataViewColumn has been
 160 chosen for sorting. Usually, the user clicks on a column header for
 161 sorting, the data will be sorted alphanumerically. If any other
 162 order (e.g. by index or order of appearance) is required, then this
 163 should be used. See also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
 164 for a model which makes use of this.
 165
 166 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 167
 168 \constfunc{bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
 169
 170 Override this to indicate of {\it item} is a container, i.e. if
 171 it can have child items.
 172
 173 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 174
 175 \func{bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 176
 177 Call this to inform the model that an item has been added
 178 to the data.
 179
 180 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 181
 182 \func{bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
 183
 184 Call this to inform the model that an item has changed.
 185
 186 \membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
 187
 188 \func{bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 189
 190 Call this to inform the model that an item has been deleted.
 191
 192 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 193
 194 \func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 195
 196 Remove the {\it notifier} from the list of notifiers.
 197
 198 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 199
 200 \func{void}{Resort}{\void}
 201
 202 Call this to initiate a resort after the sort function has
 203 been changed.
 204
 205 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 206
 207 \func{bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 208
 209 This gets called in order to set a value in the data model.
 210 The most common scenario is that the wxDataViewCtrl calls
 211 this method after the user changed some data in the view.
 212 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 213 has to be called!
 214
 215 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 216
 217 \func{bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 218
 219 Call this to inform this model that a value in
 220 the model has been changed.
 221