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