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}.
  37
  38 Note that wxDataViewModel does not define the position or
  39 index of any item in the control since several control might
  40 display the data differently, but wxDataViewModel does
  41 provide a \helpref{Compare}{wxdataviewmodelcompare} method
  42 which the wxDataViewCtrl may use to sort the data either
  43 in conjunction with a column header or without (see
  44 \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
  45
  46 This class maintains a list of
  47 \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
  48 which link this class to the specific implementations on the
  49 supported platforms so that e.g. calling
  50 \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
  51 on this model will just call
  52 \helpref{wxDataViewModelNotifier::ValueChanged}{wxdataviewmodelnotifiervaluechanged}
  53 for each notifier that has been added. You can also add
  54 your own notifier in order to get informed about any changes
  55 to the data in the list model.
  56
  57 Currently wxWidgets provides the following models apart
  58 from the base model:
  59 \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}.
  60 It is planned to add helper classes for simple tree
  61 and list stores in the future.
  62
  63 \wxheading{Derived from}
  64
  65 \helpref{wxObjectRefData}{wxobjectrefdata}
  66
  67 \wxheading{Include files}
  68
  69 <wx/dataview.h>
  70
  71 \wxheading{Library}
  72
  73 \helpref{wxAdv}{librarieslist}
  74
  75
  76
  77 \latexignore{\rtfignore{\wxheading{Members}}}
  78
  79 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
  80
  81 \func{}{wxDataViewModel}{\void}
  82
  83 Constructor.
  84
  85 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
  86
  87 \func{}{\destruct{wxDataViewModel}}{\void}
  88
  89 Destructor. This should not be called directly. Use DecRef() instead.
  90
  91
  92 \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
  93
  94 \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
  95
  96 Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
  97 to the model.
  98
  99 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
 100
 101 \func{virtual bool}{Cleared}{\void}
 102
 103 Called to inform the model that all data has been deleted.
 104
 105 \membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
 106
 107 \func{virtual int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}
 108
 109 The compare function to be used by control. The default compare function
 110 sorts by container and other items separately and in ascending order.
 111 Override this for a different sorting behaviour.
 112
 113 See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
 114
 115 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 116
 117 \constfunc{virtual unsigned int}{GetColumnCount}{\void}
 118
 119 Override this to indicate the number of columns in the model.
 120
 121 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 122
 123 \constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}
 124
 125 Override this to indicate what type of data is stored in the
 126 column specified by {\it col}. This should return a string
 127 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 128
 129 \membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren}
 130
 131 \constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }
 132
 133 Override this so the control can query the child items of
 134 an item. Returns the number of items.
 135
 136 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 137
 138 \constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 139
 140 Override this to indicate which wxDataViewItem representing the parent
 141 of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
 142
 143 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 144
 145 \constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 146
 147 Override this to indicate the value of {\it item}
 148 A \helpref{wxVariant}{wxvariant} is used to store the data.
 149
 150
 151 \membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}
 152
 153 \constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}}
 154
 155 Override this method to indicate if a container item merely
 156 acts as a headline (or for categorisation) or if it also
 157 acts a normal item with entries for futher columns. By
 158 default returns {\it false}.
 159
 160 \membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
 161
 162 \constfunc{virtual bool}{HasDefaultCompare}{\void}
 163
 164 Override this to indicate that the model provides a default compare
 165 function that the control should use if no wxDataViewColumn has been
 166 chosen for sorting. Usually, the user clicks on a column header for
 167 sorting, the data will be sorted alphanumerically. If any other
 168 order (e.g. by index or order of appearance) is required, then this
 169 should be used. See also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
 170 for a model which makes use of this.
 171
 172 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 173
 174 \constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
 175
 176 Override this to indicate of {\it item} is a container, i.e. if
 177 it can have child items.
 178
 179 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 180
 181 \func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 182
 183 Call this to inform the model that an item has been added
 184 to the data.
 185
 186 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 187
 188 \func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
 189
 190 Call this to inform the model that an item has changed.
 191
 192 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 193 event (in which the column fields will not be set) to the user.
 194
 195 \membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}
 196
 197 \func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 198
 199 Call this to inform the model that several items have been added
 200 to the data.
 201
 202 \membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}
 203
 204 \func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}}
 205
 206 Call this to inform the model that several items have changed.
 207
 208 This will eventually emit wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 209 events (in which the column fields will not be set) to the user.
 210
 211 \membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}
 212
 213 \func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 214
 215 Call this to inform the model that several items have been deleted.
 216
 217 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 218
 219 \func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 220
 221 Remove the {\it notifier} from the list of notifiers.
 222
 223 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 224
 225 \func{virtual void}{Resort}{\void}
 226
 227 Call this to initiate a resort after the sort function has
 228 been changed.
 229
 230 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 231
 232 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 233
 234 This gets called in order to set a value in the data model.
 235 The most common scenario is that the wxDataViewCtrl calls
 236 this method after the user changed some data in the view.
 237 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 238 has to be called!
 239
 240 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 241
 242 \func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 243
 244 Call this to inform this model that a value in the model has
 245 been changed. This is also called from wxDataViewCtrl's
 246 internal editing code, e.g. when editing a text field
 247 in the control.
 248
 249 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 250 event to the user.
 251