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{GetChildren}{wxdataviewmodelgetchildren},
  12 \helpref{GetColumnCount}{wxdataviewmodelgetcolumncount},
  13 \helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and
  14 \helpref{GetValue}{wxdataviewmodelgetvalue} in order to
  15 define the data model which acts as an interface between
  16 your actual data and the wxDataViewCtrl. Since you will
  17 usually also allow the wxDataViewCtrl to change your data
  18 through its graphical interface, you will also have to override
  19 \helpref{SetValue}{wxdataviewmodelsetvalue} which the
  20 wxDataViewCtrl will call when a change to some data has been
  21 commited.
  22
  23 wxDataViewModel (as indeed the entire wxDataViewCtrl
  24 code) is using \helpref{wxVariant}{wxvariant} to store data and
  25 its type in a generic way. wxVariant can be extended to contain
  26 almost any data without changes to the original class.
  27
  28 The data that is presented through this data model is expected
  29 to change at run-time. You need to inform the data model when
  30 a change happened. Depending on what happened you need to call
  31 one of the following methods:
  32 \helpref{ValueChanged}{wxdataviewmodelvaluechanged},
  33 \helpref{ItemAdded}{wxdataviewmodelitemadded},
  34 \helpref{ItemDeleted}{wxdataviewmodelitemdeleted},
  35 \helpref{ItemChanged}{wxdataviewmodelitemchanged},
  36 \helpref{Cleared}{wxdataviewmodelcleared}. There are
  37 plural forms for notification of addition, change
  38 or removal of several item at once. See
  39 \helpref{ItemsAdded}{wxdataviewmodelitemsadded},
  40 \helpref{ItemsDeleted}{wxdataviewmodelitemsdeleted},
  41 \helpref{ItemsChanged}{wxdataviewmodelitemschanged}.
  42
  43 Note that wxDataViewModel does not define the position or
  44 index of any item in the control because different controls
  45 might display the same data differently. wxDataViewModel does
  46 provide a \helpref{Compare}{wxdataviewmodelcompare} method
  47 which the wxDataViewCtrl may use to sort the data either
  48 in conjunction with a column header or without (see
  49 \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}).
  50
  51 This class maintains a list of
  52 \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
  53 which link this class to the specific implementations on the
  54 supported platforms so that e.g. calling
  55 \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
  56 on this model will just call
  57 \helpref{wxDataViewModelNotifier::ValueChanged}{wxdataviewmodelnotifiervaluechanged}
  58 for each notifier that has been added. You can also add
  59 your own notifier in order to get informed about any changes
  60 to the data in the list model.
  61
  62 Currently wxWidgets provides the following models apart
  63 from the base model:
  64 \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel},
  65 \helpref{wxDataViewTreeStore}{wxdataviewtreestore}.
  66
  67 Note that wxDataViewModel is reference counted, derives from
  68 \helpref{wxObjectRefData}{wxobjectrefdata} and cannot be deleted
  69 directly as it can be shared by several wxDataViewCtrls. This
  70 implies that you need to decrease the reference count after
  71 associating the model with a control like this:
  72
  73 {\small%
  74 \begin{verbatim}
  75     wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL );
  76     wxDataViewModel *musicModel = new MyMusicModel;
  77     m_musicCtrl->AssociateModel( musicModel );
  78     musicModel->DecRef();  // avoid memory leak !!
  79     // add columns now
  80 \end{verbatim}
  81 }%
  82
  83 \wxheading{Derived from}
  84
  85 \helpref{wxObjectRefData}{wxobjectrefdata}
  86
  87 \wxheading{Include files}
  88
  89 <wx/dataview.h>
  90
  91 \wxheading{Library}
  92
  93 \helpref{wxAdv}{librarieslist}
  94
  95
  96
  97 \latexignore{\rtfignore{\wxheading{Members}}}
  98
  99
 100 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
 101
 102 \func{}{wxDataViewModel}{\void}
 103
 104 Constructor.
 105
 106
 107 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
 108
 109 \func{}{\destruct{wxDataViewModel}}{\void}
 110
 111 Destructor. This should not be called directly. Use DecRef() instead.
 112
 113
 114
 115 \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
 116
 117 \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 118
 119 Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
 120 to the model.
 121
 122
 123 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
 124
 125 \func{virtual bool}{Cleared}{\void}
 126
 127 Called to inform the model that all data has been cleared. The
 128 control will reread the data from the model again.
 129
 130
 131 \membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
 132
 133 \func{virtual int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}
 134
 135 The compare function to be used by control. The default compare function
 136 sorts by container and other items separately and in ascending order.
 137 Override this for a different sorting behaviour.
 138
 139 See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
 140
 141
 142 \membersection{wxDataViewModel::GetAttr}\label{wxdataviewmodelgetattr}
 143
 144 \func{bool}{GetAttr}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}, \param{wxDataViewItemAttr\& }{attr}}
 145
 146 Oberride this to indicate that the item has special font attributes.
 147 This only affects the
 148 \helpref{wxDataViewTextRendererText}{wxdataviewtextrendererattr} renderer.
 149
 150 See also \helpref{wxDataViewItemAttr}{wxdataviewitemattr}.
 151
 152 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 153
 154 \constfunc{virtual unsigned int}{GetColumnCount}{\void}
 155
 156 Override this to indicate the number of columns in the model.
 157
 158
 159 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 160
 161 \constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}
 162
 163 Override this to indicate what type of data is stored in the
 164 column specified by {\it col}. This should return a string
 165 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 166
 167
 168 \membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren}
 169
 170 \constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }
 171
 172 Override this so the control can query the child items of
 173 an item. Returns the number of items.
 174
 175
 176 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 177
 178 \constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 179
 180 Override this to indicate which wxDataViewItem representing the parent
 181 of {\it item} or an invalid wxDataViewItem if the the root item is
 182 the parent item.
 183
 184
 185 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 186
 187 \constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 188
 189 Override this to indicate the value of {\it item}
 190 A \helpref{wxVariant}{wxvariant} is used to store the data.
 191
 192
 193
 194 \membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}
 195
 196 \constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}}
 197
 198 Override this method to indicate if a container item merely
 199 acts as a headline (or for categorisation) or if it also
 200 acts a normal item with entries for futher columns. By
 201 default returns {\it false}.
 202
 203
 204 \membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
 205
 206 \constfunc{virtual bool}{HasDefaultCompare}{\void}
 207
 208 Override this to indicate that the model provides a default compare
 209 function that the control should use if no wxDataViewColumn has been
 210 chosen for sorting. Usually, the user clicks on a column header for
 211 sorting, the data will be sorted alphanumerically. If any other
 212 order (e.g. by index or order of appearance) is required, then this
 213 should be used. See also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
 214 for a model which makes use of this.
 215
 216
 217 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 218
 219 \constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
 220
 221 Override this to indicate of {\it item} is a container, i.e. if
 222 it can have child items.
 223
 224
 225 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 226
 227 \func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 228
 229 Call this to inform the model that an item has been added
 230 to the data.
 231
 232
 233 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 234
 235 \func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
 236
 237 Call this to inform the model that an item has changed.
 238
 239 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 240 event (in which the column fields will not be set) to the user.
 241
 242
 243 \membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
 244
 245 \func{virtual bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 246
 247 Call this to inform the model that an item has been deleted from the data.
 248
 249
 250 \membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}
 251
 252 \func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 253
 254 Call this to inform the model that several items have been added
 255 to the data.
 256
 257
 258 \membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}
 259
 260 \func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}}
 261
 262 Call this to inform the model that several items have changed.
 263
 264 This will eventually emit wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 265 events (in which the column fields will not be set) to the user.
 266
 267
 268 \membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}
 269
 270 \func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 271
 272 Call this to inform the model that several items have been deleted.
 273
 274
 275 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 276
 277 \func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 278
 279 Remove the {\it notifier} from the list of notifiers.
 280
 281
 282 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 283
 284 \func{virtual void}{Resort}{\void}
 285
 286 Call this to initiate a resort after the sort function has
 287 been changed.
 288
 289
 290 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 291
 292 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 293
 294 This gets called in order to set a value in the data model.
 295 The most common scenario is that the wxDataViewCtrl calls
 296 this method after the user changed some data in the view.
 297 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 298 has to be called!
 299
 300
 301 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 302
 303 \func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 304
 305 Call this to inform this model that a value in the model has
 306 been changed. This is also called from wxDataViewCtrl's
 307 internal editing code, e.g. when editing a text field
 308 in the control.
 309
 310 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 311 event to the user.
 312