]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/listctrl.tex
Implemented wxLocale::IsAvailable for unix systems
[wxWidgets.git] / docs / latex / wx / listctrl.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: listctrl.tex
3 %% Purpose: wxListCtrl docs
4 %% Author:
5 %% Modified by:
6 %% Created:
7 %% RCS-ID: $Id$
8 %% Copyright: (c) wxWidgets
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxListCtrl}}\label{wxlistctrl}
13
14 A list control presents lists in a number of formats: list view, report view,
15 icon view and small icon view. In any case, elements are numbered from zero.
16 For all these modes, the items are stored in the control and must be added to
17 it using \helpref{InsertItem}{wxlistctrlinsertitem} method.
18
19 A special case of report view quite different from the other modes of the list
20 control is a virtual control in which the items data (including text, images
21 and attributes) is managed by the main program and is requested by the control
22 itself only when needed which allows to have controls with millions of items
23 without consuming much memory. To use virtual list control you must use
24 \helpref{SetItemCount}{wxlistctrlsetitemcount} first and overload at least
25 \helpref{OnGetItemText}{wxlistctrlongetitemtext} (and optionally
26 \helpref{OnGetItemImage}{wxlistctrlongetitemimage} or \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage} and
27 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}) to return the information
28 about the items when the control requests it. Virtual list control can be used
29 as a normal one except that no operations which can take time proportional to
30 the number of items in the control happen -- this is required to allow having a
31 practically infinite number of items. For example, in a multiple selection
32 virtual list control, the selections won't be sent when many items are selected
33 at once because this could mean iterating over all the items.
34
35 Using many of wxListCtrl features is shown in the
36 \helpref{corresponding sample}{samplelistctrl}.
37
38 To intercept events from a list control, use the event table macros described
39 in \helpref{wxListEvent}{wxlistevent}.
40
41 \wxheading{Derived from}
42
43 \helpref{wxControl}{wxcontrol}\\
44 \helpref{wxWindow}{wxwindow}\\
45 \helpref{wxEvtHandler}{wxevthandler}\\
46 \helpref{wxObject}{wxobject}
47
48 \wxheading{Include files}
49
50 <wx/listctrl.h>
51
52 \wxheading{Window styles}
53
54 \twocolwidtha{7cm}
55 \begin{twocollist}\itemsep=0pt
56 \twocolitem{\windowstyle{wxLC\_LIST}}{Multicolumn list view, with optional small icons.
57 Columns are computed automatically, i.e. you don't set columns as in wxLC\_REPORT. In other words,
58 the list wraps, unlike a wxListBox.}
59 \twocolitem{\windowstyle{wxLC\_REPORT}}{Single or multicolumn report view, with optional header.}
60 \twocolitem{\windowstyle{wxLC\_VIRTUAL}}{The application provides items text on demand. May only be used with wxLC\_REPORT.}
61 \twocolitem{\windowstyle{wxLC\_ICON}}{Large icon view, with optional labels.}
62 \twocolitem{\windowstyle{wxLC\_SMALL\_ICON}}{Small icon view, with optional labels.}
63 \twocolitem{\windowstyle{wxLC\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only. }
64 \twocolitem{\windowstyle{wxLC\_ALIGN\_LEFT}}{Icons align to the left. }
65 \twocolitem{\windowstyle{wxLC\_AUTOARRANGE}}{Icons arrange themselves. Win32 only. }
66 \twocolitem{\windowstyle{wxLC\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.}
67 \twocolitem{\windowstyle{wxLC\_NO\_HEADER}}{No header in report mode. }
68 \twocolitem{\windowstyle{wxLC\_SINGLE\_SEL}}{Single selection (default is multiple).}
69 \twocolitem{\windowstyle{wxLC\_SORT\_ASCENDING}}{Sort in ascending order (must still supply a comparison callback in SortItems.}
70 \twocolitem{\windowstyle{wxLC\_SORT\_DESCENDING}}{Sort in descending order (must still supply a comparison callback in SortItems.}
71 \twocolitem{\windowstyle{wxLC\_HRULES}}{Draws light horizontal rules between rows in report mode.}
72 \twocolitem{\windowstyle{wxLC\_VRULES}}{Draws light vertical rules between columns in report mode.}
73 \end{twocollist}
74
75 See also \helpref{window styles overview}{windowstyles}.
76
77 \wxheading{Event handling}
78
79 To process input from a list control, use these event handler macros to direct input to member
80 functions that take a \helpref{wxListEvent}{wxlistevent} argument.
81
82 \twocolwidtha{7cm}
83 \begin{twocollist}\itemsep=0pt
84 \twocolitem{{\bf EVT\_LIST\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
85 \twocolitem{{\bf EVT\_LIST\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
86 \twocolitem{{\bf EVT\_LIST\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
87 \twocolitem{{\bf EVT\_LIST\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
88 \twocolitem{{\bf EVT\_LIST\_DELETE\_ITEM(id, func)}}{Delete an item.}
89 \twocolitem{{\bf EVT\_LIST\_DELETE\_ALL\_ITEMS(id, func)}}{Delete all items.}
90 %\twocolitem{{\bf EVT\_LIST\_GET\_INFO(id, func)}}{Request information from the application, usually the item text.}
91 %\twocolitem{{\bf EVT\_LIST\_SET\_INFO(id, func)}}{Information is being supplied (not implemented).}
92 \twocolitem{{\bf EVT\_LIST\_ITEM\_SELECTED(id, func)}}{The item has been selected.}
93 \twocolitem{{\bf EVT\_LIST\_ITEM\_DESELECTED(id, func)}}{The item has been deselected.}
94 \twocolitem{{\bf EVT\_LIST\_ITEM\_ACTIVATED(id, func)}}{The item has been activated (ENTER or double click).}
95 \twocolitem{{\bf EVT\_LIST\_ITEM\_FOCUSED(id, func)}}{The currently focused item has changed.}
96 \twocolitem{{\bf EVT\_LIST\_ITEM\_MIDDLE\_CLICK(id, func)}}{The middle mouse button has been clicked on an item.}
97 \twocolitem{{\bf EVT\_LIST\_ITEM\_RIGHT\_CLICK(id, func)}}{The right mouse button has been clicked on an item.}
98 \twocolitem{{\bf EVT\_LIST\_KEY\_DOWN(id, func)}}{A key has been pressed.}
99 \twocolitem{{\bf EVT\_LIST\_INSERT\_ITEM(id, func)}}{An item has been inserted.}
100 \twocolitem{{\bf EVT\_LIST\_COL\_CLICK(id, func)}}{A column ({\bf m\_col}) has been left-clicked.}
101 \twocolitem{{\bf EVT\_LIST\_COL\_RIGHT\_CLICK(id, func)}}{A column ({\bf m\_col}) has been right-clicked.}
102 \twocolitem{{\bf EVT\_LIST\_COL\_BEGIN\_DRAG(id, func)}}{The user started resizing a column - can be vetoed.}
103 \twocolitem{{\bf EVT\_LIST\_COL\_DRAGGING(id, func)}}{The divider between columns is being dragged.}
104 \twocolitem{{\bf EVT\_LIST\_COL\_END\_DRAG(id, func)}}{A column has been resized by the user.}
105 \twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control}
106 \end{twocollist}%
107
108 \wxheading{See also}
109
110 \helpref{wxListCtrl overview}{wxlistctrloverview}, \helpref{wxListView}{wxlistview}, \helpref{wxListBox}{wxlistbox},\rtfsp
111 \helpref{wxTreeCtrl}{wxtreectrl}, \helpref{wxImageList}{wximagelist}, \helpref{wxListEvent}{wxlistevent},
112 \helpref{wxListItem}{wxlistitem}
113
114 \latexignore{\rtfignore{\wxheading{Members}}}
115
116
117 \membersection{wxListCtrl::wxListCtrl}\label{wxlistctrlctor}
118
119 \func{}{wxListCtrl}{\void}
120
121 Default constructor.
122
123 \func{}{wxListCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
124 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
125 \param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxListCtrlNameStr}}
126
127 Constructor, creating and showing a list control.
128
129 \wxheading{Parameters}
130
131 \docparam{parent}{Parent window. Must not be NULL.}
132
133 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
134
135 \docparam{pos}{Window position.}
136
137 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
138 appropriately.}
139
140 \docparam{style}{Window style. See \helpref{wxListCtrl}{wxlistctrl}.}
141
142 \docparam{validator}{Window validator.}
143
144 \docparam{name}{Window name.}
145
146 \wxheading{See also}
147
148 \helpref{wxListCtrl::Create}{wxlistctrlcreate}, \helpref{wxValidator}{wxvalidator}
149
150
151 \membersection{wxListCtrl::\destruct{wxListCtrl}}\label{wxlistctrldtor}
152
153 \func{void}{\destruct{wxListCtrl}}{\void}
154
155 Destructor, destroying the list control.
156
157
158 \membersection{wxListCtrl::Arrange}\label{wxlistctrlarrange}
159
160 \func{bool}{Arrange}{\param{int }{flag = wxLIST\_ALIGN\_DEFAULT}}
161
162 Arranges the items in icon or small icon view. This only has effect on Win32. {\it flag} is one of:
163
164 \twocolwidtha{5cm}
165 \begin{twocollist}\itemsep=0pt
166 \twocolitem{wxLIST\_ALIGN\_DEFAULT}{Default alignment.}
167 \twocolitem{wxLIST\_ALIGN\_LEFT}{Align to the left side of the control.}
168 \twocolitem{wxLIST\_ALIGN\_TOP}{Align to the top side of the control.}
169 \twocolitem{wxLIST\_ALIGN\_SNAP\_TO\_GRID}{Snap to grid.}
170 \end{twocollist}
171
172
173 \membersection{wxListCtrl::AssignImageList}\label{wxlistctrlassignimagelist}
174
175 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
176
177 Sets the image list associated with the control and
178 takes ownership of it (i.e. the control will, unlike when using
179 SetImageList, delete the list when destroyed). {\it which} is one of
180 wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).
181
182 \wxheading{See also}
183
184 \helpref{wxListCtrl::SetImageList}{wxlistctrlsetimagelist}
185
186
187 \membersection{wxListCtrl::ClearAll}\label{wxlistctrlclearall}
188
189 \func{void}{ClearAll}{}
190
191 Deletes all items and all columns.
192
193
194 \membersection{wxListCtrl::Create}\label{wxlistctrlcreate}
195
196 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
197 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
198 \param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxListCtrlNameStr}}
199
200 Creates the list control. See \helpref{wxListCtrl::wxListCtrl}{wxlistctrlctor} for further details.
201
202
203 \membersection{wxListCtrl::DeleteAllItems}\label{wxlistctrldeleteallitems}
204
205 \func{bool}{DeleteAllItems}{}
206
207 Deletes all items in the list control.
208
209 {\bf NB:} This function does {\it not} send the
210 {\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event because deleting many items
211 from the control would be too slow then (unlike \helpref{DeleteItem}{wxlistctrldeleteitem}).
212
213
214 \membersection{wxListCtrl::DeleteColumn}\label{wxlistctrldeletecolumn}
215
216 \func{bool}{DeleteColumn}{\param{int }{col}}
217
218 Deletes a column.
219
220
221 \membersection{wxListCtrl::DeleteItem}\label{wxlistctrldeleteitem}
222
223 \func{bool}{DeleteItem}{\param{long }{item}}
224
225 Deletes the specified item. This function sends the
226 {\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event for the item being deleted.
227
228 See also: \helpref{DeleteAllItems}{wxlistctrldeleteallitems}
229
230
231 \membersection{wxListCtrl::EditLabel}\label{wxlistctrledit}
232
233 \func{void}{EditLabel}{\param{long }{item}}
234
235 Starts editing the label of the given item. This function generates a
236 EVT\_LIST\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
237 text control will appear for in-place editing.
238
239 If the user changed the label (i.e. s/he does not press ESC or leave
240 the text control without changes, a EVT\_LIST\_END\_LABEL\_EDIT event
241 will be sent which can be vetoed as well.
242
243
244 \membersection{wxListCtrl::EnsureVisible}\label{wxlistctrlensurevisible}
245
246 \func{bool}{EnsureVisible}{\param{long }{item}}
247
248 Ensures this item is visible.
249
250
251 \membersection{wxListCtrl::FindItem}\label{wxlistctrlfinditem}
252
253 \func{long}{FindItem}{\param{long }{start}, \param{const wxString\& }{str}, \param{const bool }{partial = false}}
254
255 Find an item whose label matches this string, starting from {\it start} or
256 the beginning if {\it start} is -1. The string comparison is case
257 insensitive. If {\it partial} is true then this method will look for
258 items which begin with {\it str}.
259
260 \func{long}{FindItem}{\param{long }{start}, \param{long }{data}}
261
262 Find an item whose data matches this data, starting from {\it start} or
263 the beginning if 'start' is -1.
264
265 \func{long}{FindItem}{\param{long }{start}, \param{const wxPoint\& }{pt}, \param{int }{direction}}
266
267 Find an item nearest this position in the specified direction, starting from
268 {\it start} or the beginning if {\it start} is -1.
269
270 \pythonnote{In place of a single overloaded method name, wxPython
271 implements the following methods:\par
272 \indented{2cm}{\begin{twocollist}
273 \twocolitem{{\bf FindItem(start, str, partial=false)}}{}
274 \twocolitem{{\bf FindItemData(start, data)}}{}
275 \twocolitem{{\bf FindItemAtPos(start, point, direction)}}{}
276 \end{twocollist}}
277 }
278
279 \perlnote{In wxPerl there are three methods instead of a single overloaded
280 method:\par
281 \indented{2cm}{\begin{twocollist}
282 \twocolitem{{\bf FindItem( start, str, partial = false ) }}{}
283 \twocolitem{{\bf FindItemData( start, data ) }}{}
284 \twocolitem{{\bf FindItemAtPos( start, point, direction )}}{}
285 \end{twocollist}
286 }}
287
288
289 \membersection{wxListCtrl::GetColumn}\label{wxlistctrlgetcolumn}
290
291 \constfunc{bool}{GetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
292
293 Gets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
294 information.
295
296 \perlnote{In wxPerl this method takes only the {\bf col} parameter and
297 returns a Wx::ListItem ( or undef ).}
298
299
300 \membersection{wxListCtrl::GetColumnCount}\label{wxlistctrlgetcolumncount}
301
302 \constfunc{int}{GetColumnCount}{\void}
303
304 Returns the number of columns.
305
306
307 \membersection{wxListCtrl::GetColumnWidth}\label{wxlistctrlgetcolumnwidth}
308
309 \constfunc{int}{GetColumnWidth}{\param{int }{col}}
310
311 Gets the column width (report view only).
312
313
314 \membersection{wxListCtrl::GetCountPerPage}\label{wxlistctrlgetcountperpage}
315
316 \constfunc{int}{GetCountPerPage}{\void}
317
318 Gets the number of items that can fit vertically in the
319 visible area of the list control (list or report view)
320 or the total number of items in the list control (icon
321 or small icon view).
322
323
324 \membersection{wxListCtrl::GetEditControl}\label{wxlistctrlgeteditcontrol}
325
326 \constfunc{wxTextCtrl *}{GetEditControl}{\void}
327
328 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
329 if no label is being edited.
330
331 {\bf NB:} It is currently only implemented for wxMSW.
332
333
334 \membersection{wxListCtrl::GetImageList}\label{wxlistctrlgetimagelist}
335
336 \constfunc{wxImageList*}{GetImageList}{\param{int }{which}}
337
338 Returns the specified image list. {\it which} may be one of:
339
340 \twocolwidtha{5cm}
341 \begin{twocollist}\itemsep=0pt
342 \twocolitem{\windowstyle{wxIMAGE\_LIST\_NORMAL}}{The normal (large icon) image list.}
343 \twocolitem{\windowstyle{wxIMAGE\_LIST\_SMALL}}{The small icon image list.}
344 \twocolitem{\windowstyle{wxIMAGE\_LIST\_STATE}}{The user-defined state image list (unimplemented).}
345 \end{twocollist}
346
347
348 \membersection{wxListCtrl::GetItem}\label{wxlistctrlgetitem}
349
350 \constfunc{bool}{GetItem}{\param{wxListItem\& }{info}}
351
352 Gets information about the item. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
353 information.
354
355 You must call {\it info.SetId()} to the ID of item you're interested in
356 before calling this method.
357
358 \pythonnote{The wxPython version of this method takes an integer parameter
359 for the item ID, an optional integer for the column number, and
360 returns the wxListItem object.}
361
362 \perlnote{In wxPerl this method takes as parameter the {\bf ID} of the item
363 and ( optionally ) the column, and returns a Wx::ListItem object.}
364
365
366 \membersection{wxListCtrl::GetItemBackgroundColour}\label{wxlistctrlgetitembackgroundcolour}
367
368 \constfunc{wxColour}{GetItemBackgroundColour}{\param{long }{item}}
369
370 Returns the colour for this item. If the item has no specific colour, returns
371 an invalid colour (and not the default background control of the control
372 itself).
373
374 \wxheading{See also}
375
376 \helpref{GetItemTextColour}{wxlistctrlgetitemtextcolour}
377
378
379 \membersection{wxListCtrl::GetItemCount}\label{wxlistctrlgetitemcount}
380
381 \constfunc{int}{GetItemCount}{\void}
382
383 Returns the number of items in the list control.
384
385
386 \membersection{wxListCtrl::GetItemData}\label{wxlistctrlgetitemdata}
387
388 \constfunc{long}{GetItemData}{\param{long }{item}}
389
390 Gets the application-defined data associated with this item.
391
392
393 \membersection{wxListCtrl::GetItemFont}\label{wxlistctrlgetitemfont}
394
395 \constfunc{wxFont}{GetItemFont}{\param{long }{item}}
396
397 Returns the item's font.
398
399
400 \membersection{wxListCtrl::GetItemPosition}\label{wxlistctrlgetitemposition}
401
402 \constfunc{bool}{GetItemPosition}{\param{long }{item}, \param{wxPoint\& }{pos}}
403
404 Returns the position of the item, in icon or small icon view.
405
406 \pythonnote{The wxPython version of this method accepts only the item
407 ID and returns the wxPoint.}
408
409 \perlnote{In wxPerl this method takes only the {\bf item} parameter and
410 returns a Wx::Point ( or undef ).}
411
412
413 \membersection{wxListCtrl::GetItemRect}\label{wxlistctrlgetitemrect}
414
415 \constfunc{bool}{GetItemRect}{\param{long }{item}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
416
417 Returns the rectangle representing the item's size and position, in physical
418 coordinates.
419
420 {\it code} is one of wxLIST\_RECT\_BOUNDS, wxLIST\_RECT\_ICON, wxLIST\_RECT\_LABEL.
421
422 \pythonnote{The wxPython version of this method accepts only the item
423 ID and code and returns the wxRect.}
424
425 \perlnote{In wxPerl this method takes only the {\bf item} parameter and
426 returns a Wx::Rect ( or undef ).}
427
428
429
430 \membersection{wxListCtrl::GetSubItemRect}\label{wxlistctrlgetsubitemrect}
431
432 \constfunc{bool}{GetSubItemRect}{\param{long }{item}, \param{long }{subItem}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
433
434 Returns the rectangle representing the size and position, in physical
435 coordinates, of the given subitem, i.e. the part of the row \arg{item} in the
436 column \arg{subItem}.
437
438 This method is only meaningfull when the wxListCtrl is in the report mode. If
439 \arg{subItem} parameter is equal to the special value
440 \texttt{wxLIST\_GETSUBITEMRECT\_WHOLEITEM} the return value is the same as
441 for \helpref{GetItemRect}{wxlistctrlgetitemrect}.
442
443 \arg{code} can be one of \texttt{wxLIST\_RECT\_BOUNDS},
444 \texttt{wxLIST\_RECT\_ICON} or \texttt{wxLIST\_RECT\_LABEL}.
445
446 \newsince{2.7.0}
447
448
449 \membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
450
451 \constfunc{wxSize}{GetItemSpacing}{\void}
452
453 Retrieves the spacing between icons in pixels: horizontal spacing is returned
454 as \texttt{x} component of the \helpref{wxSize}{wxsize} object and the vertical
455 spacing as its \texttt{y} component.
456
457
458
459 \membersection{wxListCtrl::GetItemState}\label{wxlistctrlgetitemstate}
460
461 \constfunc{int}{GetItemState}{\param{long }{item}, \param{long }{stateMask}}
462
463 Gets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
464
465 The {\bf stateMask} indicates which state flags are of interest.
466
467
468 \membersection{wxListCtrl::GetItemText}\label{wxlistctrlgetitemtext}
469
470 \constfunc{wxString}{GetItemText}{\param{long }{item}}
471
472 Gets the item text for this item.
473
474
475 \membersection{wxListCtrl::GetItemTextColour}\label{wxlistctrlgetitemtextcolour}
476
477 \constfunc{wxColour}{GetItemTextColour}{\param{long }{item}}
478
479 Returns the colour for this item. If the item has no specific colour, returns
480 an invalid colour (and not the default foreground control of the control itself
481 as this wouldn't allow distinguishing between items having the same colour as
482 the current control foreground and items with default colour which, hence, have
483 always the same colour as the control).
484
485
486 \membersection{wxListCtrl::GetNextItem}\label{wxlistctrlgetnextitem}
487
488 \constfunc{long}{GetNextItem}{\param{long }{item}, \param{int }{geometry = wxLIST\_NEXT\_ALL}, \param{int }{state = wxLIST\_STATE\_DONTCARE}}
489
490 Searches for an item with the given geometry or state, starting from
491 {\it item} but excluding the {\it item} itself. If {\it item} is -1,
492 the first item that matches the specified flags will be returned.
493
494 Returns the first item with given state following {\it item} or -1 if
495 no such item found.
496
497 This function may be used to find all selected items in the control like this:
498
499 \begin{verbatim}
500 long item = -1;
501 for ( ;; )
502 {
503 item = listctrl->GetNextItem(item,
504 wxLIST_NEXT_ALL,
505 wxLIST_STATE_SELECTED);
506 if ( item == -1 )
507 break;
508
509 // this item is selected - do whatever is needed with it
510 wxLogMessage("Item %ld is selected.", item);
511 }
512 \end{verbatim}
513
514 {\it geometry} can be one of:
515
516 \twocolwidtha{5cm}
517 \begin{twocollist}\itemsep=0pt
518 \twocolitem{wxLIST\_NEXT\_ABOVE}{Searches for an item above the specified item.}
519 \twocolitem{wxLIST\_NEXT\_ALL}{Searches for subsequent item by index.}
520 \twocolitem{wxLIST\_NEXT\_BELOW}{Searches for an item below the specified item.}
521 \twocolitem{wxLIST\_NEXT\_LEFT}{Searches for an item to the left of the specified item.}
522 \twocolitem{wxLIST\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.}
523 \end{twocollist}
524
525 {\bf NB:} this parameter is only supported by wxMSW currently and ignored on
526 other platforms.
527
528 {\it state} can be a bitlist of the following:
529
530 \twocolwidtha{5cm}
531 \begin{twocollist}\itemsep=0pt
532 \twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is.}
533 \twocolitem{wxLIST\_STATE\_DROPHILITED}{The item indicates it is a drop target.}
534 \twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
535 \twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
536 \twocolitem{wxLIST\_STATE\_CUT}{The item is selected as part of a cut and paste operation.}
537 \end{twocollist}
538
539
540 \membersection{wxListCtrl::GetSelectedItemCount}\label{wxlistctrlgetselecteditemcount}
541
542 \constfunc{int}{GetSelectedItemCount}{\void}
543
544 Returns the number of selected items in the list control.
545
546
547 \membersection{wxListCtrl::GetTextColour}\label{wxlistctrlgettextcolour}
548
549 \constfunc{wxColour}{GetTextColour}{\void}
550
551 Gets the text colour of the list control.
552
553
554 \membersection{wxListCtrl::GetTopItem}\label{wxlistctrlgettopitem}
555
556 \constfunc{long}{GetTopItem}{\void}
557
558 Gets the index of the topmost visible item when in
559 list or report view.
560
561
562
563 \membersection{wxListCtrl::GetViewRect}\label{wxlistctrlgetviewrect}
564
565 \constfunc{wxRect}{GetViewRect}{\void}
566
567 Returns the rectangle taken by all items in the control. In other words, if the
568 controls client size were equal to the size of this rectangle, no scrollbars
569 would be needed and no free space would be left.
570
571 Note that this function only works in the icon and small icon views, not in
572 list or report views (this is a limitation of the native Win32 control).
573
574
575
576 \membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
577
578 \constfunc{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}, \param{long *}{ptrSubItem}}
579
580 Determines which item (if any) is at the specified point,
581 giving details in {\it flags}. Returns index of the item or {\tt wxNOT\_FOUND}
582 if no item is at the specified point.
583 {\it flags} will be a combination of the following flags:
584
585 \twocolwidtha{5cm}
586 \begin{twocollist}\itemsep=0pt
587 \twocolitem{wxLIST\_HITTEST\_ABOVE}{Above the client area.}
588 \twocolitem{wxLIST\_HITTEST\_BELOW}{Below the client area.}
589 \twocolitem{wxLIST\_HITTEST\_NOWHERE}{In the client area but below the last item.}
590 \twocolitem{wxLIST\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
591 \twocolitem{wxLIST\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
592 \twocolitem{wxLIST\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
593 \twocolitem{wxLIST\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
594 \twocolitem{wxLIST\_HITTEST\_TOLEFT}{To the right of the client area.}
595 \twocolitem{wxLIST\_HITTEST\_TORIGHT}{To the left of the client area.}
596 \twocolitem{wxLIST\_HITTEST\_ONITEM}{Combination of wxLIST\_HITTEST\_ONITEMICON, wxLIST\_HITTEST\_ONITEMLABEL,
597 wxLIST\_HITTEST\_ONITEMSTATEICON.}
598 \end{twocollist}
599
600 If \arg{ptrSubItem} is not \NULL and the wxListCtrl is in the report
601 mode the subitem (or column) number will also be provided.
602 This feature is only available in version 2.7.0 or higher and is currently only
603 implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on
604 the host system or the value stored in \arg{ptrSubItem} will be always -1. To
605 compile this feature into wxWidgets library you need to have access to
606 commctrl.h of version 4.70 that is provided by Microsoft.
607
608 \pythonnote{A tuple of values is returned in the wxPython version of
609 this method. The first value is the item id and the second is the
610 flags value mentioned above.}
611
612 \perlnote{In wxPerl this method only takes the {\bf point} parameter
613 and returns a 2-element list {\tt ( item, flags )}.}
614
615
616 \membersection{wxListCtrl::InsertColumn}\label{wxlistctrlinsertcolumn}
617
618 \func{long}{InsertColumn}{\param{long }{col}, \param{wxListItem\& }{info}}
619
620 \func{long}{InsertColumn}{\param{long }{col}, \param{const wxString\& }{heading}, \param{int }{format = wxLIST\_FORMAT\_LEFT},\rtfsp
621 \param{int }{width = -1}}
622
623 For report view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
624
625 \pythonnote{In place of a single overloaded method name, wxPython
626 implements the following methods:\par
627 \indented{2cm}{\begin{twocollist}
628 \twocolitem{{\bf InsertColumn(col, heading, format=wxLIST\_FORMAT\_LEFT,
629 width=-1)}}{Creates a column using a header string only.}
630 \twocolitem{{\bf InsertColumnItem(col, item)}}{Creates a column using a
631 wxListItem.}
632 \end{twocollist}}
633 }
634
635
636 \membersection{wxListCtrl::InsertItem}\label{wxlistctrlinsertitem}
637
638 \func{long}{InsertItem}{\param{wxListItem\& }{info}}
639
640 Inserts an item, returning the index of the new item if successful,
641 -1 otherwise.
642
643 \func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}}
644
645 Inserts a string item.
646
647 \func{long}{InsertItem}{\param{long }{index}, \param{int }{imageIndex}}
648
649 Inserts an image item.
650
651 \func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}, \param{int }{imageIndex}}
652
653 Insert an image/string item.
654
655 \wxheading{Parameters}
656
657 \docparam{info}{wxListItem object}
658
659 \docparam{index}{Index of the new item, supplied by the application}
660
661 \docparam{label}{String label}
662
663 \docparam{imageIndex}{index into the image list associated with this control and view style}
664
665 \pythonnote{In place of a single overloaded method name, wxPython
666 implements the following methods:\par
667 \indented{2cm}{\begin{twocollist}\itemsep=0pt
668 \twocolitem{{\bf InsertItem(item)}}{Inserts an item using a wxListItem.}
669 \twocolitem{{\bf InsertStringItem(index, label)}}{Inserts a string item.}
670 \twocolitem{{\bf InsertImageItem(index, imageIndex)}}{Inserts an image item.}
671 \twocolitem{{\bf InsertImageStringItem(index, label, imageIndex)}}{Insert an image/string item.}
672 \end{twocollist}}
673 }
674
675 \perlnote{In wxPerl there are four methods instead of a single overloaded
676 method:\par
677 \indented{2cm}{\begin{twocollist}
678 \twocolitem{{\bf InsertItem( item )}}{Inserts a Wx::ListItem}
679 \twocolitem{{\bf InsertStringItem( index, label )}}{Inserts a string item}
680 \twocolitem{{\bf InsertImageItem( index, imageIndex )}}{Inserts an image item}
681 \twocolitem{{\bf InsertImageStringItem( index, label, imageIndex )}}{Inserts
682 an item with a string and an image}
683 \end{twocollist}
684 }}
685
686
687 \membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}
688
689 \constfunc{virtual wxListItemAttr *}{OnGetItemAttr}{\param{long }{item}}
690
691 This function may be overloaded in the derived class for a control with
692 {\tt wxLC\_VIRTUAL} style. It should return the attribute for the
693 for the specified {\tt item} or {\tt NULL} to use the default appearance
694 parameters.
695
696 wxListCtrl will not delete the pointer or keep a reference of it. You can
697 return the same wxListItemAttr pointer for every OnGetItemAttr call.
698
699 The base class version always returns {\tt NULL}.
700
701 \wxheading{See also}
702
703 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
704 \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
705 \helpref{OnGetItemText}{wxlistctrlongetitemtext}
706
707
708 \membersection{wxListCtrl::OnGetItemImage}\label{wxlistctrlongetitemimage}
709
710 \constfunc{virtual int}{OnGetItemImage}{\param{long }{item}}
711
712 This function must be overloaded in the derived class for a control with
713 {\tt wxLC\_VIRTUAL} style having an \helpref{image list}{wxlistctrlsetimagelist}
714 (if the control doesn't have an image list, it is not necessary to overload
715 it). It should return the index of the items image in the controls image list
716 or $-1$ for no image.
717 In a control with {\tt wxLC\_REPORT} style, OnGetItemImage only gets called for
718 the first column of each line.
719
720 The base class version always returns $-1$.
721
722 \wxheading{See also}
723
724 \helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
725 \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
726 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
727
728 \membersection{wxListCtrl::OnGetItemColumnImage}\label{wxlistctrlongetitemcolumnimage}
729
730 \constfunc{virtual int}{OnGetItemColumnImage}{\param{long }{item}, \param{long }{column}}
731
732 Overload this function in the derived class for a control with
733 {\tt wxLC\_VIRTUAL} and {\tt wxLC\_REPORT} styles in order to specify the image
734 index for the given line and column.
735
736 The base class version always calls OnGetItemImage for the first column, else
737 it returns $-1$.
738
739 \wxheading{See also}
740
741 \helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
742 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
743 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
744
745 \membersection{wxListCtrl::OnGetItemText}\label{wxlistctrlongetitemtext}
746
747 \constfunc{virtual wxString}{OnGetItemText}{\param{long }{item}, \param{long }{column}}
748
749 This function {\bf must} be overloaded in the derived class for a control with
750 {\tt wxLC\_VIRTUAL} style. It should return the string containing the text of
751 the given {\it column} for the specified {\tt item}.
752
753 \wxheading{See also}
754
755 \helpref{SetItemCount}{wxlistctrlsetitemcount},\\
756 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
757 \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
758 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
759
760
761 \membersection{wxListCtrl::RefreshItem}\label{wxlistctrlrefreshitem}
762
763 \func{void}{RefreshItem}{\param{long }{item}}
764
765 Redraws the given {\it item}. This is only useful for the virtual list controls
766 as without calling this function the displayed value of the item doesn't change
767 even when the underlying data does change.
768
769 \wxheading{See also}
770
771 \helpref{RefreshItems}{wxlistctrlrefreshitems}
772
773
774
775 \membersection{wxListCtrl::RefreshItems}\label{wxlistctrlrefreshitems}
776
777 \func{void}{RefreshItems}{\param{long }{itemFrom}, \param{long }{itemTo}}
778
779 Redraws the items between {\it itemFrom} and {\it itemTo}. The starting item
780 must be less than or equal to the ending one.
781
782 Just as \helpref{RefreshItem}{wxlistctrlrefreshitem} this is only useful for
783 virtual list controls.
784
785
786
787 \membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}
788
789 \func{bool}{ScrollList}{\param{int }{dx}, \param{int }{dy}}
790
791 Scrolls the list control. If in icon, small icon or report view mode,
792 {\it dx} specifies the number of pixels to scroll. If in list view mode,
793 {\it dx} specifies the number of columns to scroll. {\it dy} always specifies
794 the number of pixels to scroll vertically.
795
796 {\bf NB:} This method is currently only implemented in the Windows version.
797
798
799 \membersection{wxListCtrl::SetBackgroundColour}\label{wxlistctrlsetbackgroundcolour}
800
801 \func{void}{SetBackgroundColour}{\param{const wxColour\& }{col}}
802
803 Sets the background colour (GetBackgroundColour already implicit in
804 wxWindow class).
805
806
807 \membersection{wxListCtrl::SetColumn}\label{wxlistctrlsetcolumn}
808
809 \func{bool}{SetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
810
811 Sets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
812 information.
813
814
815 \membersection{wxListCtrl::SetColumnWidth}\label{wxlistctrlsetcolumnwidth}
816
817 \func{bool}{SetColumnWidth}{\param{int }{col}, \param{int }{width}}
818
819 Sets the column width.
820
821 {\it width} can be a width in pixels or wxLIST\_AUTOSIZE (-1) or wxLIST\_AUTOSIZE\_USEHEADER (-2).
822 wxLIST\_AUTOSIZE will resize the column to the length of its longest item. wxLIST\_AUTOSIZE\_USEHEADER
823 will resize the column to the length of the header (Win32) or 80 pixels (other platforms).
824
825 In small or normal icon view, {\it col} must be -1, and the column width is set for all columns.
826
827
828 \membersection{wxListCtrl::SetImageList}\label{wxlistctrlsetimagelist}
829
830 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
831
832 Sets the image list associated with the control. {\it which} is one of
833 wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).
834
835 This method does not take ownership of the image list, you have to
836 delete it yourself.
837
838 \wxheading{See also}
839
840 \helpref{wxListCtrl::AssignImageList}{wxlistctrlassignimagelist}
841
842
843
844 \membersection{wxListCtrl::SetItem}\label{wxlistctrlsetitem}
845
846 \func{bool}{SetItem}{\param{wxListItem\& }{info}}
847
848 \func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const }{wxString\& label}, \param{int }{imageId = -1}}
849
850 Sets information about the item.
851
852 wxListItem is a class with the following members:
853
854 \twocolwidtha{5cm}
855 \begin{twocollist}\itemsep=0pt
856 \twocolitem{long m\_mask}{Indicates which fields are valid. See the list of valid mask flags below.}
857 \twocolitem{long m\_itemId}{The zero-based item position.}
858 \twocolitem{int m\_col}{Zero-based column, if in report mode.}
859 \twocolitem{long m\_state}{The state of the item. See the list of valid state flags below.}
860 \twocolitem{long m\_stateMask}{A mask indicating which state flags are valid. See the list of valid state flags below.}
861 \twocolitem{wxString m\_text}{The label/header text.}
862 \twocolitem{int m\_image}{The zero-based index into an image list.}
863 \twocolitem{long m\_data}{Application-defined data.}
864 \twocolitem{int m\_format}{For columns only: the format. Can be wxLIST\_FORMAT\_LEFT, wxLIST\_FORMAT\_RIGHT or
865 wxLIST\_FORMAT\_CENTRE.}
866 \twocolitem{int m\_width}{For columns only: the column width.}
867 \end{twocollist}
868
869 The {\bf m\_mask} member contains a bitlist specifying which of the other fields are valid. The flags are:
870
871 \twocolwidtha{5cm}
872 \begin{twocollist}\itemsep=0pt
873 \twocolitem{wxLIST\_MASK\_STATE}{The {\bf m\_state} field is valid.}
874 \twocolitem{wxLIST\_MASK\_TEXT}{The {\bf m\_text} field is valid.}
875 \twocolitem{wxLIST\_MASK\_IMAGE}{The {\bf m\_image} field is valid.}
876 \twocolitem{wxLIST\_MASK\_DATA}{The {\bf m\_data} field is valid.}
877 \twocolitem{wxLIST\_MASK\_WIDTH}{The {\bf m\_width} field is valid.}
878 \twocolitem{wxLIST\_MASK\_FORMAT}{The {\bf m\_format} field is valid.}
879 \end{twocollist}
880
881 The {\bf m\_stateMask} and {\bf m\_state} members take flags from the following:
882
883 \twocolwidtha{5cm}
884 \begin{twocollist}\itemsep=0pt
885 \twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is. Win32 only. }
886 \twocolitem{wxLIST\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event. Win32 only. }
887 \twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
888 \twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
889 \twocolitem{wxLIST\_STATE\_CUT}{The item is in the cut state. Win32 only. }
890 \end{twocollist}
891
892 The wxListItem object can also contain item-specific colour and font
893 information: for this you need to call one of SetTextColour(),
894 SetBackgroundColour() or SetFont() functions on it passing it the colour/font
895 to use. If the colour/font is not specified, the default list control
896 colour/font is used.
897
898 \func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const wxString\& }{label}, \param{int }{imageId = -1}}
899
900 Sets a string field at a particular column.
901
902 \pythonnote{In place of a single overloaded method name, wxPython
903 implements the following methods:\par
904 \indented{2cm}{\begin{twocollist}
905 \twocolitem{{\bf SetItem(item)}}{Sets information about the given wxListItem.}
906 \twocolitem{{\bf SetStringItem(index, col, label, imageId)}}{Sets a
907 string or image at a given location.}
908 \end{twocollist}}
909 }
910
911 \membersection{wxListCtrl::SetItemBackgroundColour}\label{wxlistctrlsetitembackgroundcolour}
912
913 \func{void}{SetItemBackgroundColour}{\param{long }{item}, \param{const wxColour\& }{col}}
914
915 Sets the background colour for this item. This function only works in report view.
916
917 The colour can be retrieved using
918 \helpref{GetItemBackgroundColour}{wxlistctrlgetitembackgroundcolour}.
919
920
921
922 \membersection{wxListCtrl::SetItemCount}\label{wxlistctrlsetitemcount}
923
924 \func{void}{SetItemCount}{\param{long }{count}}
925
926 This method can only be used with virtual list controls. It is used to indicate
927 to the control the number of items it contains. After calling it, the main
928 program should be ready to handle calls to various item callbacks (such as
929 \helpref{OnGetItemText}{wxlistctrlongetitemtext}) for all items in the range
930 from $0$ to {\it count}.
931
932
933 \membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}
934
935 \func{bool}{SetItemData}{\param{long }{item}, \param{long }{data}}
936
937 Associates application-defined data with this item.
938
939
940 \membersection{wxListCtrl::SetItemFont}\label{wxlistctrlsetitemfont}
941
942 \func{void}{SetItemFont}{\param{long }{item}, \param{const wxFont\& }{font}}
943
944 Sets the item's font.
945
946
947 \membersection{wxListCtrl::SetItemImage}\label{wxlistctrlsetitemimage}
948
949 \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}}
950
951 Sets the image associated with the item. The image is an index into the
952 image list associated with the list control. In report view, this only sets
953 the image for the first column.
954
955 \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}, \param{int }{selImage}}
956
957 Sets the unselected and selected images associated with the item. The images are indices into the
958 image list associated with the list control. This form is deprecated: {\it selImage} is not
959 used.
960
961
962 \membersection{wxListCtrl::SetItemColumnImage}\label{wxlistctrlsetitemcolumnimage}
963
964 \func{bool}{SetItemImage}{\param{long }{item}, \param{long }{column}\param{int }{image}}
965
966 Sets the image associated with the item. In report view, you can specify the column.
967 The image is an index into the image list associated with the list control.
968
969
970 \membersection{wxListCtrl::SetItemPosition}\label{wxlistctrlsetitemposition}
971
972 \func{bool}{SetItemPosition}{\param{long }{item}, \param{const wxPoint\& }{pos}}
973
974 Sets the position of the item, in icon or small icon view. Windows only.
975
976
977 \membersection{wxListCtrl::SetItemState}\label{wxlistctrlsetitemstate}
978
979 \func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}}
980
981 Sets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
982
983 The {\bf stateMask} indicates which state flags are valid.
984
985
986 \membersection{wxListCtrl::SetItemText}\label{wxlistctrlsetitemtext}
987
988 \func{void}{SetItemText}{\param{long }{item}, \param{const wxString\& }{text}}
989
990 Sets the item text for this item.
991
992
993 \membersection{wxListCtrl::SetItemTextColour}\label{wxlistctrlsetitemtextcolour}
994
995 \func{void}{SetItemTextColour}{\param{long }{item}, \param{const wxColour\& }{col}}
996
997 Sets the colour for this item. This function only works in report view.
998
999 The colour can be retrieved using
1000 \helpref{GetItemTextColour}{wxlistctrlgetitemtextcolour}.
1001
1002
1003 \membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle}
1004
1005 \func{void}{SetSingleStyle}{\param{long }{style}, \param{const bool }{add = true}}
1006
1007 Adds or removes a single window style.
1008
1009
1010 \membersection{wxListCtrl::SetTextColour}\label{wxlistctrlsettextcolour}
1011
1012 \func{void}{SetTextColour}{\param{const wxColour\& }{col}}
1013
1014 Sets the text colour of the list control.
1015
1016
1017 \membersection{wxListCtrl::SetWindowStyleFlag}\label{wxlistctrlsetwindowstyleflag}
1018
1019 \func{void}{SetWindowStyleFlag}{\param{long }{style}}
1020
1021 Sets the whole window style, deleting all items.
1022
1023 \membersection{wxListCtrl::SortItems}\label{wxlistctrlsortitems}
1024
1025 \func{bool}{SortItems}{\param{wxListCtrlCompare }{fnSortCallBack}, \param{long }{data}}
1026
1027 Call this function to sort the items in the list control. Sorting is done
1028 using the specified {\it fnSortCallBack} function. This function must have the
1029 following prototype:
1030
1031 \begin{verbatim}
1032 int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
1033 \end{verbatim}
1034
1035 It is called each time when the two items must be compared and should return 0
1036 if the items are equal, negative value if the first item is less than the
1037 second one and positive value if the first one is greater than the second one
1038 (the same convention as used by {\tt qsort(3)}).
1039
1040 \wxheading{Parameters}
1041
1042 \docparam{item1}{client data associated with the first item ({\bf NOT} the index).}
1043
1044 \docparam{item2}{client data associated with the second item ({\bf NOT} the index).}
1045
1046 \docparam{data}{the value passed to SortItems() itself.}
1047
1048 Notice that the control may only be sorted on client data associated with the
1049 items, so you {\bf must} use \helpref{SetItemData}{wxlistctrlsetitemdata} if
1050 you want to be able to sort the items in the control.
1051
1052 Please see the \helpref{listctrl sample}{samplelistctrl} for an example of
1053 using this function.
1054
1055 \pythonnote{wxPython uses the sortData parameter to pass the Python
1056 function to call, so it is not available for programmer use. Call
1057 SortItems with a reference to a callable object that expects two
1058 parameters.}
1059
1060 \perlnote{In wxPerl the comparison function must take just two parameters;
1061 however, you may use a closure to achieve an effect similar to the
1062 SortItems third parameter.}
1063