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 \helpref{wxDataViewTreeStore}{wxdataviewtreestore}.
  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{virtual 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{virtual 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{virtual 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{virtual 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::GetChildren}\label{wxdataviewmodelgetchildren}
 129
 130 \constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }
 131
 132 Override this so the control can query the child items of
 133 an item. Returns the number of items.
 134
 135 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 136
 137 \constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 138
 139 Override this to indicate which wxDataViewItem representing the parent
 140 of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
 141
 142 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 143
 144 \constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 145
 146 Override this to indicate the value of {\it item}
 147 A \helpref{wxVariant}{wxvariant} is used to store the data.
 148
 149
 150 \membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}
 151
 152 \constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}}
 153
 154 Override this method to indicate if a container item merely
 155 acts as a headline (or for categorisation) or if it also
 156 acts a normal item with entries for futher columns. By
 157 default returns {\it false}.
 158
 159 \membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
 160
 161 \constfunc{virtual bool}{HasDefaultCompare}{\void}
 162
 163 Override this to indicate that the model provides a default compare
 164 function that the control should use if no wxDataViewColumn has been
 165 chosen for sorting. Usually, the user clicks on a column header for
 166 sorting, the data will be sorted alphanumerically. If any other
 167 order (e.g. by index or order of appearance) is required, then this
 168 should be used. See also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
 169 for a model which makes use of this.
 170
 171 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 172
 173 \constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
 174
 175 Override this to indicate of {\it item} is a container, i.e. if
 176 it can have child items.
 177
 178 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 179
 180 \func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 181
 182 Call this to inform the model that an item has been added
 183 to the data.
 184
 185 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 186
 187 \func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
 188
 189 Call this to inform the model that an item has changed.
 190
 191 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 192 event (in which the column fields will not be set) to the user.
 193
 194 \membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}
 195
 196 \func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 197
 198 Call this to inform the model that several items have been added
 199 to the data.
 200
 201 \membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}
 202
 203 \func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}}
 204
 205 Call this to inform the model that several items have changed.
 206
 207 This will eventually emit wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 208 events (in which the column fields will not be set) to the user.
 209
 210 \membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}
 211
 212 \func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
 213
 214 Call this to inform the model that several items have been deleted.
 215
 216 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 217
 218 \func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 219
 220 Remove the {\it notifier} from the list of notifiers.
 221
 222 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 223
 224 \func{virtual void}{Resort}{\void}
 225
 226 Call this to initiate a resort after the sort function has
 227 been changed.
 228
 229 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 230
 231 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 232
 233 This gets called in order to set a value in the data model.
 234 The most common scenario is that the wxDataViewCtrl calls
 235 this method after the user changed some data in the view.
 236 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 237 has to be called!
 238
 239 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 240
 241 \func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 242
 243 Call this to inform this model that a value in the model has
 244 been changed. This is also called from wxDataViewCtrl's
 245 internal editing code, e.g. when editing a text field
 246 in the control.
 247
 248 This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
 249 event to the user.
 250