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 Currently, this class has no functionality at all and the
   7 only existing implementation of it is the
   8 \helpref{wxDataViewListModel}{wxdataviewlistmodel}. The
   9 plan is to move all functionality of wxDataViewListModel
  10 and a to-be-written wxDataViewTreeModel into wxDataViewModel
  11 and make wxDataViewListModel and wxDataViewTreeModel subsets
  12 of the abstract wxDataViewModel.
  13
  14 \wxheading{Derived from}
  15
  16 \helpref{wxObjectRefData}{wxobjectrefdata}
  17
  18 \wxheading{Include files}
  19
  20 <wx/dataview.h>
  21
  22 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
  23
  24 \func{}{wxDataViewModel}{\void}
  25
  26 Constructor.
  27
  28 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
  29
  30 \func{}{\destruct{wxDataViewModel}}{\void}
  31
  32 Destructor.
  33
  34 \section{\class{wxDataViewListModel}}\label{wxdataviewlistmodel}
  35
  36 wxDataViewListModel is currently the only existing variant
  37 of a \helpref{wxDataViewModel}{wxdataviewmodel}. It allows
  38 to define a table like data model to be displayed by a
  39 \helpref{wxDataViewCtrl}{wxdataviewctrl}. You need to derive
  40 from this class to define your own data model.
  41
  42 You need to override \helpref{GetRowCount}{wxdataviewlistmodelgetrowcount},
  43 \helpref{GetColumnCount}{wxdataviewlistmodelgetcolumncount},
  44 \helpref{GetColumnType}{wxdataviewlistmodelgetcolumntype} and
  45 \helpref{GetValue}{wxdataviewlistmodelgetvalue} in order to
  46 define the data model (which acts as an interface between
  47 your actual data and the wxDataViewCtrl). Since you will
  48 usually also allow the wxDataViewCtrl to change your data
  49 through its graphical interface, you will also have to override
  50 \helpref{SetValue}{wxdataviewlistmodelsetvalue} which the
  51 wxDataViewCtrl will call when a change to some data has been
  52 commited.
  53
  54 The data that is presented through this data model is expected
  55 to change at run-time. You need to inform the data model that
  56 a change happens. Depending on what happened you need to call
  57 one of the following methods:
  58 \helpref{ValueChanged}{wxdataviewlistmodelvaluechanged},
  59 \helpref{RowChanged}{wxdataviewlistmodelrowchanged},
  60 \helpref{RowAppended}{wxdataviewlistmodelrowappended},
  61 \helpref{RowPrepended}{wxdataviewlistmodelrowprepended},
  62 \helpref{RowInserted}{wxdataviewlistmodelrowinserted},
  63 \helpref{RowDeleted}{wxdataviewlistmodelrowdeleted},
  64 \helpref{RowsReordered}{wxdataviewlistmodelrowsreordered} or
  65 \helpref{RowsCleared}{wxdataviewlistmodelcleared}.
  66
  67
  68
  69 wxDataViewModel and this class (as indeed the entire wxDataViewCtrl
  70 code) is using \helpref{wxVariant}{wxvariant} to store data and
  71 its type in a generic way. wxVariant can be extended to contain
  72 almost any data without changes to the original class.
  73
  74 This class maintains a list of
  75 \helpref{wxDataListViewListModelNotifier}{wxdataviewlistmodelnotifier}
  76 which link this class to the specific implementations on the
  77 supported platforms so that e.g. calling
  78 \helpref{ValueChanged}{wxdataviewlistmodelvaluechanged}
  79 on this model will just call
  80 \helpref{wxDataListViewListModelNotifier::ValueChanged}{wxdataviewlistmodelnotifiervaluechanged}
  81 for each notifier that has been added. This is used both for
  82 informing the native controls to redraw themselves and for informing
  83 e.g. the \helpref{wxDataViewSortedListModel}{wxdataviewsortedlistmodel}
  84 to resort itself. You can also add your own notifier in order
  85 to get informed about any changes to the data in the list model.
  86
  87 Additionally, this class maintains a list of all
  88 \helpref{wxDataViewColumns}{wxdataviewcolumn} which
  89 display a certain column of this list model. This is
  90 mostly used internally.
  91
  92 \wxheading{Derived from}
  93
  94 \helpref{wxDataViewModel}{wxdataviewmodel}\\
  95 \helpref{wxObject}{wxobject}
  96
  97 \wxheading{Include files}
  98
  99 <wx/dataview.h>
 100
 101
 102 \membersection{wxDataViewListModel::wxDataViewListModel}\label{wxdataviewlistmodelwxdataviewlistmodel}
 103
 104 \func{}{wxDataViewListModel}{\void}
 105
 106 Constructor.
 107
 108 \membersection{wxDataViewListModel::\destruct{wxDataViewListModel}}\label{wxdataviewlistmodeldtor}
 109
 110 \func{}{\destruct{wxDataViewListModel}}{\void}
 111
 112 Destructor.
 113
 114 \membersection{wxDataViewListModel::AddNotifier}\label{wxdataviewlistmodeladdnotifier}
 115
 116 \func{void}{AddNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
 117
 118 Adds {\it notifier} to the internal list of notifers.
 119
 120 See also \helpref{RemoveNotifier}{wxdataviewlistmodelremovenotifier}.
 121
 122 \membersection{wxDataViewListModel::Cleared}\label{wxdataviewlistmodelcleared}
 123
 124 \func{bool}{virtual Cleared}{\void}
 125
 126 Call this if all data in your model has been cleared.
 127
 128 \membersection{wxDataViewListModel::GetColumnCount}\label{wxdataviewlistmodelgetcolumncount}
 129
 130 \func{virtual unsigned int}{GetColumnCount}{\void}
 131
 132 Override this to indicate, how many columns the list
 133 model has.
 134
 135 \membersection{wxDataViewListModel::GetColumnType}\label{wxdataviewlistmodelgetcolumntype}
 136
 137 \func{virtual wxString}{GetColType}{\param{unsigned int }{col}}
 138
 139 Override this to indicate what type of data is stored in the
 140 column specified by {\it col}. This should return a string
 141 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 142
 143 \membersection{wxDataViewListModel::GetRowCount}\label{wxdataviewlistmodelgetrowcount}
 144
 145 \func{virtual unsigned int}{GetRowCount}{\void}
 146
 147 Override this to indicate, how many rows the list
 148 model has.
 149
 150 \membersection{wxDataViewListModel::GetValue}\label{wxdataviewlistmodelgetvalue}
 151
 152 \func{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 153
 154 Override this to indicate the value of a given value
 155 in the list model. A \helpref{wxVariant}{wxvariant}
 156 is used to store the data.
 157
 158 \membersection{wxDataViewListModel::RemoveNotifier}\label{wxdataviewlistmodelremovenotifier}
 159
 160 \func{void}{RemoveNotifier}{\param{wxDataViewListModelNotifier* }{notifier}}
 161
 162 Removes the notifier from the list of notifiers.
 163
 164 See also \helpref{AddNotifier}{wxdataviewlistmodeladdnotifier}.
 165
 166 \membersection{wxDataViewListModel::RowAppended}\label{wxdataviewlistmodelrowappended}
 167
 168 \func{virtual bool}{RowAppended}{\void}
 169
 170 Call this if a row has been appended to the list model.
 171
 172 \membersection{wxDataViewListModel::RowChanged}\label{wxdataviewlistmodelrowchanged}
 173
 174 \func{virtual bool}{RowChanged}{\param{unsigned int }{row}}
 175
 176 Call this if the values of this row have been changed.
 177
 178 \membersection{wxDataViewListModel::RowDeleted}\label{wxdataviewlistmodelrowdeleted}
 179
 180 \func{virtual bool}{RowDeleted}{\param{unsigned int }{row}}
 181
 182 Call this if this row has been deleted.
 183
 184 \membersection{wxDataViewListModel::RowInserted}\label{wxdataviewlistmodelrowinserted}
 185
 186 \func{virtual bool}{RowInserted}{\param{unsigned int }{before}}
 187
 188 Call this if a row has been inserted.
 189
 190 \membersection{wxDataViewListModel::RowPrepended}\label{wxdataviewlistmodelrowprepended}
 191
 192 \func{virtual bool}{RowPrepended}{\void}
 193
 194 Call this if a row has been prepended.
 195
 196 \membersection{wxDataViewListModel::RowsReordered}\label{wxdataviewlistmodelrowsreordered}
 197
 198 \func{virtual bool}{RowsReordered}{\param{unsigned int* }{new\_order}}
 199
 200 Call this if the rows have been reorderd.
 201
 202 \membersection{wxDataViewListModel::SetValue}\label{wxdataviewlistmodelsetvalue}
 203
 204 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 205
 206 This method gets called by e.g. the wxDataViewCtrl class if a
 207 value has been changed through its graphical interface. You
 208 need to override this method in order to update the data in
 209 the underlying data structur. Afterwards,
 210 \helpref{ValueChanged}{wxdataviewlistmodelvaluechanged} is called.
 211
 212
 213 \membersection{wxDataViewListModel::ValueChanged}\label{wxdataviewlistmodelvaluechanged}
 214
 215 \func{virtual bool}{ValueChanged}{\param{unsigned int }{col}, \param{unsigned int }{row}}
 216
 217 Call this if a value in the model has been changed.
 218
 219
 220 \section{\class{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodel}
 221
 222 This class is used for sorting data. It does not contain any
 223 data itself. Rather, it provides a sorted interface for
 224 another list model.
 225
 226 Currently, the sorting algorithm isn't thread safe. This needs
 227 to be fixed.
 228
 229 \wxheading{Derived from}
 230
 231 \helpref{wxDataViewListModel}{wxdataviewlistmodel}\\
 232 \helpref{wxDataViewModel}{wxdataviewmodel}\\
 233 \helpref{wxObject}{wxobject}
 234
 235 \wxheading{Include files}
 236
 237 <wx/dataview.h>
 238
 239 \membersection{wxDataViewSortedListModel::wxDataViewSortedListModel}\label{wxdataviewsortedlistmodelwxdataviewsortedlistmodel}
 240
 241 \func{}{wxDataViewSortedListModel}{\param{wxDataViewListModel* }{child}}
 242
 243 Constructor. {\it child} is the child data model the data of
 244 which this model is supposed to present in a sorted way.
 245
 246 \membersection{wxDataViewSortedListModel::\destruct{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodeldtor}
 247
 248 \func{}{\destruct{wxDataViewSortedListModel}}{\void}
 249
 250 Destructor.
 251
 252 \membersection{wxDataViewSortedListModel::GetAscending}\label{wxdataviewsortedlistmodelgetascending}
 253
 254 \func{bool}{GetAscending}{\void}
 255
 256 Returns true if the data is sorted in ascending order.
 257
 258 \membersection{wxDataViewSortedListModel::Resort}\label{wxdataviewsortedlistmodelresort}
 259
 260 \func{void}{Resort}{\void}
 261
 262 Tell the model to resort its data.
 263
 264 \membersection{wxDataViewSortedListModel::SetAscending}\label{wxdataviewsortedlistmodelsetascending}
 265
 266 \func{void}{SetAscending}{\param{bool }{ascending}}
 267
 268 Set the sort order of the data.
 269