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}{wxdataviewmodelitesmadded},
  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 shares by several wxDataViewCtrl. 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, wxDefaultPosition,
  76                                                      wxDefaultSize, wxDV_MULTIPLE );
  77     wxDataViewModel *musicModel = new MyMusicModel;
  78     m_musicCtrl->AssociateModel( musicModel );
  79     musicModel->DecRef();  // avoid memory leak !!
  80
  81     // add columns now
  82 \end{verbatim}
  83 }%
  84
  85 \wxheading{Derived from}
  86
  87 \helpref{wxObjectRefData}{wxobjectrefdata}
  88
  89 \wxheading{Include files}
  90
  91 <wx/dataview.h>
  92
  93 \wxheading{Library}
  94
  95 \helpref{wxAdv}{librarieslist}
  96
  97
  98
  99 \latexignore{\rtfignore{\wxheading{Members}}}
 100
 101 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
 102
 103 \func{}{wxDataViewModel}{\void}
 104
 105 Constructor.
 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 \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
 115
 116 \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 117
 118 Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
 119 to the model.
 120
 121 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
 122
 123 \func{virtual bool}{Cleared}{\void}
 124
 125 Called to inform the model that all data has been deleted.
 126
 127 \membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
 128
 129 \func{virtual int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}
 130
 131 The compare function to be used by control. The default compare function
 132 sorts by container and other items separately and in ascending order.
 133 Override this for a different sorting behaviour.
 134
 135 See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
 136
 137 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 138
 139 \constfunc{virtual unsigned int}{GetColumnCount}{\void}
 140
 141 Override this to indicate the number of columns in the model.
 142
 143 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 144
 145 \constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}
 146
 147 Override this to indicate what type of data is stored in the
 148 column specified by {\it col}. This should return a string
 149 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 150
 151 \membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren}
 152
 153 \constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }
 154
 155 Override this so the control can query the child items of
 156 an item. Returns the number of items.
 157
 158 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 159
 160 \constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 161
 162 Override this to indicate which wxDataViewItem representing the parent
 163 of {\it item} or an invalid wxDataViewItem if the the root item is
 164 the parent item.
 165
 166 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 167
 168 \constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 169
 170 Override this to indicate the value of {\it item}
 171 A \helpref{wxVariant}{wxvariant} is used to store the data.
 172
 173
 174 \membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}
 175
 176 \constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}}
 177
 178 Override this method to indicate if a container item merely
 179 acts as a headline (or for categorisation) or if it also
 180 acts a normal item with entries for futher columns. By
 181 default returns {\it false}.
 182
 183 \membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
 184
 185 \constfunc{virtual bool}{HasDefaultCompare}{\void}
 186
 187 Override this to indicate that the model provides a default compare
 188 function that the control should use if no wxDataViewColumn has been
 189 chosen for sorting. Usually, the user clicks on a column header for
 190 sorting, the data will be sorted alphanumerically. If any other
 191 order (e.g. by index or order of appearance) is required, then this
 192 should be used. See also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
 193 for a model which makes use of this.
 194
 195 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 196
 197 \constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
 198
 199 Override this to indicate of {\it item} is a container, i.e. if
 200 it can have child items.
 201
 202 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 203
 204 \func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 205
 206 Call this to inform the model that an item has been added
 207 to the data.
 208
 209 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 210
 211 \func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
 212
 213 Call this to inform the model that an item has changed.
 214
 215 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 216 event (in which the column fields will not be set) to the user.
 217
 218 \membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}
 219
 220 \func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 221
 222 Call this to inform the model that several items have been added
 223 to the data.
 224
 225 \membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}
 226
 227 \func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}}
 228
 229 Call this to inform the model that several items have changed.
 230
 231 This will eventually emit wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 232 events (in which the column fields will not be set) to the user.
 233
 234 \membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}
 235
 236 \func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 237
 238 Call this to inform the model that several items have been deleted.
 239
 240 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 241
 242 \func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 243
 244 Remove the {\it notifier} from the list of notifiers.
 245
 246 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 247
 248 \func{virtual void}{Resort}{\void}
 249
 250 Call this to initiate a resort after the sort function has
 251 been changed.
 252
 253 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 254
 255 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 256
 257 This gets called in order to set a value in the data model.
 258 The most common scenario is that the wxDataViewCtrl calls
 259 this method after the user changed some data in the view.
 260 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 261 has to be called!
 262
 263 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 264
 265 \func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 266
 267 Call this to inform this model that a value in the model has
 268 been changed. This is also called from wxDataViewCtrl's
 269 internal editing code, e.g. when editing a text field
 270 in the control.
 271
 272 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 273 event to the user.
 274