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{GetColumnCount}{wxdataviewmodelgetcolumncount},
  12 \helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and
  13 \helpref{GetValue}{wxdataviewmodelgetvalue} in order to
  14 define the data model which acts as an interface between
  15 your actual data and the wxDataViewCtrl. Since you will
  16 usually also allow the wxDataViewCtrl to change your data
  17 through its graphical interface, you will also have to override
  18 \helpref{SetValue}{wxdataviewlistmodelsetvalue} which the
  19 wxDataViewCtrl will call when a change to some data has been
  20 commited.
  21
  22 wxDataViewModel (as indeed the entire wxDataViewCtrl
  23 code) is using \helpref{wxVariant}{wxvariant} to store data and
  24 its type in a generic way. wxVariant can be extended to contain
  25 almost any data without changes to the original class.
  26
  27 The data that is presented through this data model is expected
  28 to change at run-time. You need to inform the data model when
  29 a change happened. Depending on what happened you need to call
  30 one of the following methods:
  31 \helpref{ValueChanged}{wxdataviewmodelvaluechanged},
  32 \helpref{ItemAdded}{wxdataviewmodelitemadded},
  33 \helpref{ItemDeleted}{wxdataviewmodelitemdeleted},
  34 \helpref{ItemChanged}{wxdataviewmodelitemchanged},
  35 \helpref{Cleared}{wxdataviewmodelcleared}.
  36
  37 Note that wxDataViewModel does not define the position or
  38 index of any item in the control since several control might
  39 display the data differently, but wxDataViewModel does
  40 provide a \helpref{Compare}{wxdataviewmodelcompare} method
  41 which the wxDataViewCtrl may use to sort the data.
  42
  43 This class maintains a list of
  44 \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
  45 which link this class to the specific implementations on the
  46 supported platforms so that e.g. calling
  47 \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
  48 on this model will just call
  49 \helpref{wxDataViewModelNotifier::ValueChanged}{wxdataviewmodelnotifiervaluechanged}
  50 for each notifier that has been added. You can also add
  51 your own notifier in order to get informed about any changes
  52 to the data in the list model.
  53
  54 Currently wxWidgets provides the following models apart
  55 from the base model:
  56 \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}.
  57 It is planned to add helper classes for simple tree
  58 and list stores in the future.
  59
  60 \wxheading{Derived from}
  61
  62 \helpref{wxObjectRefData}{wxobjectrefdata}
  63
  64 \wxheading{Include files}
  65
  66 <wx/dataview.h>
  67
  68 \wxheading{Library}
  69
  70 \helpref{wxAdv}{librarieslist}
  71
  72
  73
  74 \latexignore{\rtfignore{\wxheading{Members}}}
  75
  76 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
  77
  78 \func{}{wxDataViewModel}{\void}
  79
  80 Constructor.
  81
  82 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
  83
  84 \func{}{\destruct{wxDataViewModel}}{\void}
  85
  86 Destructor. This should not be called directly. Use DecRef() instead.
  87
  88
  89 \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
  90
  91 \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
  92
  93 Adds a \helpref{wxDataViewModelNotifier}{wxdataviewlistmodelnotifier}
  94 to the model.
  95
  96 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
  97
  98 \func{bool}{Cleared}{\void}
  99
 100 Called to inform the model that all data has been deleted.
 101
 102 \membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
 103
 104 \func{int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}
 105
 106 The compare function to be used by control. The default compare function
 107 sorts by container and other items separately and in ascending order.
 108 Override this for a different sorting behaviour.
 109
 110 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 111
 112 \constfunc{unsigned int}{GetColumnCount}{\void}
 113
 114 Override this to indicate the number of columns in the model.
 115
 116 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 117
 118 \constfunc{wxString}{GetColumnType}{\param{unsigned int }{col}}
 119
 120 Override this to indicate what type of data is stored in the
 121 column specified by {\it col}. This should return a string
 122 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 123
 124 \membersection{wxDataViewModel::GetFirstChild}\label{wxdataviewmodelgetfirstchild}
 125
 126 \constfunc{wxDataViewItem}{GetFirstChild}{\param{const wxDataViewItem\& }{parent}}
 127
 128 To be removed.
 129
 130 \membersection{wxDataViewModel::GetNextSibling}\label{wxdataviewmodelgetnextsibling}
 131
 132 \constfunc{wxDataViewItem}{GetNextSibling}{\param{const wxDataViewItem\& }{item}}
 133
 134 To be removed.
 135
 136 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 137
 138 \constfunc{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{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 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 151
 152 \constfunc{bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
 153
 154 Override this to indicate of {\it item} is a container, i.e. if
 155 it can have child items.
 156
 157 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 158
 159 \func{bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 160
 161 Call this to inform the model that an item has been added
 162 to the data.
 163
 164 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 165
 166 \func{bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
 167
 168 Call this to inform the model that an item has changed.
 169
 170 \membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
 171
 172 \func{bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 173
 174 Call this to inform the model that an item has been deleted.
 175
 176 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 177
 178 \func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 179
 180 Remove the {\it notifier} from the list of notifiers.
 181
 182 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 183
 184 \func{void}{Resort}{\void}
 185
 186 Call this to initiate a resort after the sort function has
 187 been changed.
 188
 189 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 190
 191 \func{bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 192
 193 This gets called in order to set a value in the data model.
 194 The most common scenario is that the wxDataViewCtrl calls
 195 this method after the user changed some data in the view.
 196 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 197 has to be called!
 198
 199 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 200
 201 \func{bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 202
 203 Call this to inform this model that a value in
 204 the model has been changed.
 205