]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/listctrl.tex
Added regex to WXINC line (patch from Markus G)
[wxWidgets.git] / docs / latex / wx / listctrl.tex
CommitLineData
a660d684
KB
1\section{\class{wxListCtrl}}\label{wxlistctrl}
2
963863ad
VZ
3A list control presents lists in a number of formats: list view, report view,
4icon view and small icon view. In any case, elements are numbered from zero.
614391dc
VZ
5For all these modes, the items are stored in the control and must be added to
6it using \helpref{InsertItem}{wxlistctrlinsertitem} method.
7
8A special case of report view quite different from the other modes of the list
9control is a virtual control in which the items data (including text, images
10and attributes) is managed by the main program and is requested by the control
11itself only when needed which allows to have controls with millions of items
12without consuming much memory. To use virtual list control you must use
13\helpref{SetItemCount}{wxlistctrlsetitemcount} first and overload at least
14\helpref{OnGetItemText}{wxlistctrlongetitemtext} (and optionally
15\helpref{OnGetItemImage}{wxlistctrlongetitemimage} and
16\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}) to return the information
17about the items when the control requests it.
18
19Using many of wxListCtrl features is shown in the
963863ad
VZ
20\helpref{corresponding sample}{samplelistctrl}.
21
22To intercept events from a list control, use the event table macros described
23in \helpref{wxListEvent}{wxlistevent}.
a660d684
KB
24
25\wxheading{Derived from}
26
27\helpref{wxControl}{wxcontrol}\\
28\helpref{wxWindow}{wxwindow}\\
29\helpref{wxEvtHandler}{wxevthandler}\\
30\helpref{wxObject}{wxobject}
31
954b8ae6
JS
32\wxheading{Include files}
33
34<wx/listctrl.h>
35
a660d684
KB
36\wxheading{Window styles}
37
f7ba097d 38\twocolwidtha{7cm}
a660d684
KB
39\begin{twocollist}\itemsep=0pt
40\twocolitem{\windowstyle{wxLC\_LIST}}{multicolumn list view, with optional small icons.
41Columns are computed automatically, i.e. you don't set columns as in wxLC\_REPORT. In other words,
42the list wraps, unlike a wxListBox.}
43\twocolitem{\windowstyle{wxLC\_REPORT}}{single or multicolumn report view, with optional header.}
614391dc 44\twocolitem{\windowstyle{wxLC\_VIRTUAL}}{virtual control, may only be used with wxLC\_REPORT}
a660d684
KB
45\twocolitem{\windowstyle{wxLC\_ICON}}{Large icon view, with optional labels.}
46\twocolitem{\windowstyle{wxLC\_SMALL\_ICON}}{Small icon view, with optional labels.}
0180dad6
RR
47\twocolitem{\windowstyle{wxLC\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only. }
48\twocolitem{\windowstyle{wxLC\_ALIGN\_LEFT}}{Icons align to the left. }
49\twocolitem{\windowstyle{wxLC\_AUTOARRANGE}}{Icons arrange themselves. Win32 only. }
50\twocolitem{\windowstyle{wxLC\_USER\_TEXT}}{The application provides label text on demand, except for column headers. Win32 only. }
a660d684 51\twocolitem{\windowstyle{wxLC\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.}
0180dad6 52\twocolitem{\windowstyle{wxLC\_NO\_HEADER}}{No header in report mode. Win32 only. }
a660d684
KB
53\twocolitem{\windowstyle{wxLC\_SINGLE\_SEL}}{Single selection.}
54\twocolitem{\windowstyle{wxLC\_SORT\_ASCENDING}}{Sort in ascending order (must still supply a comparison callback in SortItems.}
55\twocolitem{\windowstyle{wxLC\_SORT\_DESCENDING}}{Sort in descending order (must still supply a comparison callback in SortItems.}
b96340e6
JS
56\twocolitem{\windowstyle{wxLC\_HRULES}}{Draws light horizontal rules between rows in report mode.}
57\twocolitem{\windowstyle{wxLC\_VRULES}}{Draws light vertical rules between columns in report mode.}
a660d684
KB
58\end{twocollist}
59
60See also \helpref{window styles overview}{windowstyles}.
61
5de76427
JS
62\wxheading{Event handling}
63
64To process input from a list control, use these event handler macros to direct input to member
65functions that take a \helpref{wxListEvent}{wxlistevent} argument.
66
67\twocolwidtha{7cm}
68\begin{twocollist}\itemsep=0pt
69\twocolitem{{\bf EVT\_LIST\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
70\twocolitem{{\bf EVT\_LIST\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
fd128b0c
RR
71\twocolitem{{\bf EVT\_LIST\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
72\twocolitem{{\bf EVT\_LIST\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
5de76427
JS
73\twocolitem{{\bf EVT\_LIST\_DELETE\_ITEM(id, func)}}{Delete an item.}
74\twocolitem{{\bf EVT\_LIST\_DELETE\_ALL\_ITEMS(id, func)}}{Delete all items.}
75\twocolitem{{\bf EVT\_LIST\_GET\_INFO(id, func)}}{Request information from the application, usually the item text.}
76\twocolitem{{\bf EVT\_LIST\_SET\_INFO(id, func)}}{Information is being supplied (not implemented).}
77\twocolitem{{\bf EVT\_LIST\_ITEM\_SELECTED(id, func)}}{The item has been selected.}
78\twocolitem{{\bf EVT\_LIST\_ITEM\_DESELECTED(id, func)}}{The item has been deselected.}
8b17ba72 79\twocolitem{{\bf EVT\_LIST\_ITEM\_ACTIVATED(id, func)}}{The item has been activated (ENTER or double click).}
5de76427
JS
80\twocolitem{{\bf EVT\_LIST\_KEY\_DOWN(id, func)}}{A key has been pressed.}
81\twocolitem{{\bf EVT\_LIST\_INSERT\_ITEM(id, func)}}{An item has been inserted.}
82\twocolitem{{\bf EVT\_LIST\_COL\_CLICK(id, func)}}{A column ({\bf m\_col}) has been left-clicked.}
a07a98db 83\twocolitem{{\bf EVT\_LIST\_ITEM\_RIGHT\_CLICK(id, func)}}{An item has been right-clicked.}
614391dc 84\twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control}
5de76427
JS
85\end{twocollist}%
86
a660d684
KB
87\wxheading{See also}
88
89\helpref{wxListCtrl overview}{wxlistctrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxTreeCtrl}{wxtreectrl},\rtfsp
90\helpref{wxImageList}{wximagelist}, \helpref{wxListEvent}{wxlistevent}
91
92\latexignore{\rtfignore{\wxheading{Members}}}
93
94\membersection{wxListCtrl::wxListCtrl}\label{wxlistctrlconstr}
95
96\func{}{wxListCtrl}{\void}
97
98Default constructor.
99
eaaa6a06 100\func{}{wxListCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
a660d684 101\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
eaaa6a06 102\param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
a660d684
KB
103
104Constructor, creating and showing a list control.
105
106\wxheading{Parameters}
107
108\docparam{parent}{Parent window. Must not be NULL.}
109
110\docparam{id}{Window identifier. A value of -1 indicates a default value.}
111
112\docparam{pos}{Window position.}
113
114\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
115appropriately.}
116
117\docparam{style}{Window style. See \helpref{wxListCtrl}{wxlistctrl}.}
118
119\docparam{validator}{Window validator.}
120
121\docparam{name}{Window name.}
122
123\wxheading{See also}
124
125\helpref{wxListCtrl::Create}{wxlistctrlcreate}, \helpref{wxValidator}{wxvalidator}
126
127\membersection{wxListCtrl::\destruct{wxListCtrl}}
128
129\func{void}{\destruct{wxListCtrl}}{\void}
130
131Destructor, destroying the list control.
132
133\membersection{wxListCtrl::Arrange}\label{wxlistctrlarrange}
134
eaaa6a06 135\func{bool}{Arrange}{\param{int }{flag = wxLIST\_ALIGN\_DEFAULT}}
a660d684 136
0180dad6 137Arranges the items in icon or small icon view. This only has effect on Win32. {\it flag} is one of:
a660d684
KB
138
139\twocolwidtha{5cm}
140\begin{twocollist}\itemsep=0pt
141\twocolitem{wxLIST\_ALIGN\_DEFAULT}{Default alignment.}
142\twocolitem{wxLIST\_ALIGN\_LEFT}{Align to the left side of the control.}
143\twocolitem{wxLIST\_ALIGN\_TOP}{Align to the top side of the control.}
144\twocolitem{wxLIST\_ALIGN\_SNAP\_TO\_GRID}{Snap to grid.}
145\end{twocollist}
146
2e12c11a
VS
147\membersection{wxListCtrl::AssignImageList}\label{wxlistctrlassignimagelist}
148
149\func{void}{AssignImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
150
151Sets the image list associated with the control and
152takes ownership of it (i.e. the control will, unlike when using
153SetImageList, delete the list when destroyed). {\it which} is one of
154wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).
155
156\wxheading{See also}
157
158\helpref{wxListCtrl::SetImageList}{wxlistctrlsetimagelist}
159
8b17ba72
RR
160\membersection{wxListCtrl::ClearAll}\label{wxlistctrlclearall}
161
162\func{void}{ClearAll}{}
163
164Deletes all items and all columns.
165
70b62288
GT
166\membersection{wxListCtrl::Create}\label{wxlistctrlcreate}
167
168\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
169\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
170\param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
171
172Creates the list control. See \helpref{wxListCtrl::wxListCtrl}{wxlistctrlconstr} for further details.
173
a660d684
KB
174\membersection{wxListCtrl::DeleteAllItems}\label{wxlistctrldeleteallitems}
175
8b17ba72 176\func{bool}{DeleteAllItems}{}
a660d684
KB
177
178Deletes all the items in the list control.
179
aa9fb2be 180{\bf NB:} This function does {\it not} send the
bffa1c77 181{\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event because deleting many items
fa482912 182from the control would be too slow then (unlike \helpref{DeleteItem}{wxlistctrldeleteitem}).
bffa1c77 183
a660d684
KB
184\membersection{wxListCtrl::DeleteColumn}\label{wxlistctrldeletecolumn}
185
eaaa6a06 186\func{bool}{DeleteColumn}{\param{int }{col}}
a660d684
KB
187
188Deletes a column.
189
2c8c812f
GT
190\membersection{wxListCtrl::DeleteItem}\label{wxlistctrldeleteitem}
191
192\func{bool}{DeleteItem}{\param{long }{item}}
193
194Deletes the specified item. This function sends the
195{\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event for the item being deleted.
196
197See also: \helpref{DeleteAllItems}{wxlistctrldeleteallitems}
198
86f975a8 199\membersection{wxListCtrl::EditLabel}\label{wxlistctrledit}
a660d684 200
fd128b0c 201\func{void}{EditLabel}{\param{long }{item}}
a660d684 202
fd128b0c
RR
203Starts editing the label of the given item. This function generates a
204EVT\_LIST\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
205text control will appear for in-place editing.
86f975a8 206
fd128b0c 207If the user changed the label (i.e. s/he does not press ESC or leave
76e1c2de 208the text control without changes, a EVT\_LIST\_END\_LABEL\_EDIT event
fd128b0c 209will be sent which can be vetoed as well.
a660d684
KB
210
211\membersection{wxListCtrl::EnsureVisible}\label{wxlistctrlensurevisible}
212
eaaa6a06 213\func{bool}{EnsureVisible}{\param{long }{item}}
a660d684
KB
214
215Ensures this item is visible.
216
217\membersection{wxListCtrl::FindItem}\label{wxlistctrlfinditem}
218
eaaa6a06 219\func{long}{FindItem}{\param{long }{start}, \param{const wxString\& }{str}, \param{const bool }{partial = FALSE}}
a660d684
KB
220
221Find an item whose label matches this string, starting from the item after {\it start} or
222the beginning if {\it start} is -1.
223
eaaa6a06 224\func{long}{FindItem}{\param{long }{start}, \param{long }{data}}
a660d684
KB
225
226Find an item whose data matches this data, starting from the item after {\it start} or
227the beginning if 'start' is -1.
228
eaaa6a06 229\func{long}{FindItem}{\param{long }{start}, \param{const wxPoint\& }{pt}, \param{int }{direction}}
a660d684
KB
230
231Find an item nearest this position in the specified direction, starting from
232the item after {\it start} or the beginning if {\it start} is -1.
233
21f280f4
RD
234\pythonnote{In place of a single overloaded method name, wxPython
235implements the following methods:\par
236\indented{2cm}{\begin{twocollist}
c9110876
VS
237\twocolitem{{\bf FindItem(start, str, partial=FALSE)}}{}
238\twocolitem{{\bf FindItemData(start, data)}}{}
239\twocolitem{{\bf FindItemAtPos(start, point, direction)}}{}
21f280f4
RD
240\end{twocollist}}
241}
242
f3539882
VZ
243\perlnote{In wxPerl there are three methods instead of a single overloaded
244method:\par
245\indented{2cm}{\begin{twocollist}
246\twocolitem{{\bf FindItem( start, str, partial = FALSE ) }}{}
247\twocolitem{{\bf FindItemData( start, data ) }}{}
248\twocolitem{{\bf FindItemAtPos( start, point, direction )}}{}
249\end{twocollist}
250}}
251
a660d684
KB
252\membersection{wxListCtrl::GetColumn}\label{wxlistctrlgetcolumn}
253
eaaa6a06 254\constfunc{bool}{GetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
a660d684
KB
255
256Gets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
257information.
258
f3539882
VZ
259\perlnote{In wxPerl this method takes only the {\bf col} parameter and
260 returns a Wx::ListItem ( or undef ).}
261
a660d684
KB
262\membersection{wxListCtrl::GetColumnWidth}\label{wxlistctrlgetcolumnwidth}
263
eaaa6a06 264\constfunc{int}{GetColumnWidth}{\param{int }{col}}
a660d684
KB
265
266Gets the column width (report view only).
267
268\membersection{wxListCtrl::GetCountPerPage}\label{wxlistctrlgetcountperpage}
269
270\constfunc{int}{GetCountPerPage}{\void}
271
272Gets the number of items that can fit vertically in the
273visible area of the list control (list or report view)
274or the total number of items in the list control (icon
275or small icon view).
276
277\membersection{wxListCtrl::GetEditControl}\label{wxlistctrlgeteditcontrol}
278
279\constfunc{wxTextCtrl\&}{GetEditControl}{\void}
280
281Gets the edit control for editing labels.
282
283\membersection{wxListCtrl::GetImageList}\label{wxlistctrlgetimagelist}
284
eaaa6a06 285\constfunc{wxImageList*}{GetImageList}{\param{int }{which}}
a660d684
KB
286
287Returns the specified image list. {\it which} may be one of:
288
289\twocolwidtha{5cm}
290\begin{twocollist}\itemsep=0pt
291\twocolitem{\windowstyle{wxIMAGE\_LIST\_NORMAL}}{The normal (large icon) image list.}
292\twocolitem{\windowstyle{wxIMAGE\_LIST\_SMALL}}{The small icon image list.}
293\twocolitem{\windowstyle{wxIMAGE\_LIST\_STATE}}{The user-defined state image list (unimplemented).}
294\end{twocollist}
295
296\membersection{wxListCtrl::GetItem}\label{wxlistctrlgetitem}
297
298\constfunc{bool}{GetItem}{\param{wxListItem\& }{info}}
299
300Gets information about the item. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
301information.
302
1ddfb726 303You must call {\it info.SetId()} to the ID of item you're interested in
e5aff4c5
VS
304before calling this method.
305
76e1c2de 306\pythonnote{The wxPython version of this method takes an integer parameter
f6bcfd97 307for the item ID, an optional integer for the column number, and
1ddfb726 308returns the wxListItem object.}
21f280f4 309
f3539882
VZ
310\perlnote{In wxPerl this method takes as parameter the {\bf ID} of the item
311and ( optionally ) the column, and returns a Wx::ListItem object.}
312
70b62288
GT
313\membersection{wxListCtrl::GetItemCount}\label{wxlistctrlgetitemcount}
314
315\constfunc{int}{GetItemCount}{\void}
316
317Returns the number of items in the list control.
318
a660d684
KB
319\membersection{wxListCtrl::GetItemData}\label{wxlistctrlgetitemdata}
320
eaaa6a06 321\constfunc{long}{GetItemData}{\param{long }{item}}
a660d684
KB
322
323Gets the application-defined data associated with this item.
324
325\membersection{wxListCtrl::GetItemPosition}\label{wxlistctrlgetitemposition}
326
eaaa6a06 327\constfunc{bool}{GetItemPosition}{\param{long }{item}, \param{wxPoint\& }{pos}}
a660d684
KB
328
329Returns the position of the item, in icon or small icon view.
330
b456d571 331\pythonnote{The wxPython version of this method accepts only the item
21f280f4
RD
332ID and returns the wxPoint.}
333
f3539882
VZ
334\perlnote{In wxPerl this method takes only the {\bf item} parameter and
335returns a Wx::Point ( or undef ).}
336
a660d684
KB
337\membersection{wxListCtrl::GetItemRect}\label{wxlistctrlgetitemrect}
338
eaaa6a06 339\constfunc{bool}{GetItemRect}{\param{long }{item}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
a660d684
KB
340
341Returns the rectangle representing the item's size and position, in client coordinates.
342
343{\it code} is one of wxLIST\_RECT\_BOUNDS, wxLIST\_RECT\_ICON, wxLIST\_RECT\_LABEL.
344
b456d571 345\pythonnote{The wxPython version of this method accepts only the item
aa9fb2be 346ID and code and returns the wxRect.}
21f280f4 347
f3539882
VZ
348\perlnote{In wxPerl this method takes only the {\bf item} parameter and
349retutrns a Wx::Rect ( or undef ).}
350
a660d684
KB
351\membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
352
353\constfunc{int}{GetItemSpacing}{\param{bool }{isSmall}}
354
355Retrieves the spacing between icons in pixels.
356If {\it small} is TRUE, gets the spacing for the small icon
357view, otherwise the large icon view.
358
70b62288
GT
359\membersection{wxListCtrl::GetItemState}\label{wxlistctrlgetitemstate}
360
361\constfunc{int}{GetItemState}{\param{long }{item}, \param{long }{stateMask}}
362
363Gets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
364
365The {\bf stateMask} indicates which state flags are of interest.
366
a660d684
KB
367\membersection{wxListCtrl::GetItemText}\label{wxlistctrlgetitemtext}
368
eaaa6a06 369\constfunc{wxString}{GetItemText}{\param{long }{item}}
a660d684
KB
370
371Gets the item text for this item.
372
373\membersection{wxListCtrl::GetNextItem}\label{wxlistctrlgetnextitem}
374
eaaa6a06 375\constfunc{long}{GetNextItem}{\param{long }{item}, \param{int }{geometry = wxLIST\_NEXT\_ALL}, \param{int }{state = wxLIST\_STATE\_DONTCARE}}
a660d684 376
aa9fb2be 377Searches for an item with the given goemetry or state, starting from
8e21d9ad
VZ
378{\it item} but excluding the {\it item} itself. If {\it item} is -1,
379the first item that matches the specified flags will be returned.
380
381Returns the first item with given state following {\it item} or -1 if
382no such item found.
383
384This function may be used to find all selected items in the control like this:
fa482912 385
8e21d9ad
VZ
386\begin{verbatim}
387 long item = -1;
388 for ( ;; )
389 {
390 item = listctrl->GetNextItem(item,
391 wxLIST_NEXT_ALL,
392 wxLIST_STATE_SELECTED);
393 if ( item == -1 )
394 break;
395
396 // this item is selected - do whatever is needed with it
397 wxLogMessage("Item %ld is selected."), item);
398 }
399\end{verbatim}
a660d684
KB
400
401{\it geometry} can be one of:
402
403\twocolwidtha{5cm}
404\begin{twocollist}\itemsep=0pt
405\twocolitem{wxLIST\_NEXT\_ABOVE}{Searches for an item above the specified item.}
406\twocolitem{wxLIST\_NEXT\_ALL}{Searches for subsequent item by index.}
407\twocolitem{wxLIST\_NEXT\_BELOW}{Searches for an item below the specified item.}
408\twocolitem{wxLIST\_NEXT\_LEFT}{Searches for an item to the left of the specified item.}
409\twocolitem{wxLIST\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.}
410\end{twocollist}
411
8e21d9ad
VZ
412{\bf NB:} this parameters is only supported by wxMSW currently and ignored on
413other platforms.
414
a660d684
KB
415{\it state} can be a bitlist of the following:
416
417\twocolwidtha{5cm}
418\begin{twocollist}\itemsep=0pt
419\twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is.}
420\twocolitem{wxLIST\_STATE\_DROPHILITED}{The item indicates it is a drop target.}
421\twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
422\twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
423\twocolitem{wxLIST\_STATE\_CUT}{The item is selected as part of a cut and paste operation.}
424\end{twocollist}
425
426\membersection{wxListCtrl::GetSelectedItemCount}\label{wxlistctrlgetselecteditemcount}
427
428\constfunc{int}{GetSelectedItemCount}{\void}
429
430Returns the number of selected items in the list control.
431
432\membersection{wxListCtrl::GetTextColour}\label{wxlistctrlgettextcolour}
433
434\constfunc{wxColour}{GetTextColour}{\void}
435
436Gets the text colour of the list control.
437
438\membersection{wxListCtrl::GetTopItem}\label{wxlistctrlgettopitem}
439
440\constfunc{long}{GetTopItem}{\void}
441
442Gets the index of the topmost visible item when in
443list or report view.
444
445\membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
446
447\func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
448
449Determines which item (if any) is at the specified point,
450giving details in {\it flags}. {\it flags} will be a combination of the following flags:
451
452\twocolwidtha{5cm}
453\begin{twocollist}\itemsep=0pt
454\twocolitem{wxLIST\_HITTEST\_ABOVE}{Above the client area.}
455\twocolitem{wxLIST\_HITTEST\_BELOW}{Below the client area.}
456\twocolitem{wxLIST\_HITTEST\_NOWHERE}{In the client area but below the last item.}
457\twocolitem{wxLIST\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
458\twocolitem{wxLIST\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
459\twocolitem{wxLIST\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
460\twocolitem{wxLIST\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
461\twocolitem{wxLIST\_HITTEST\_TOLEFT}{To the right of the client area.}
462\twocolitem{wxLIST\_HITTEST\_TORIGHT}{To the left of the client area.}
463\twocolitem{wxLIST\_HITTEST\_ONITEM}{Combination of wxLIST\_HITTEST\_ONITEMICON, wxLIST\_HITTEST\_ONITEMLABEL,
464wxLIST\_HITTEST\_ONITEMSTATEICON.}
465\end{twocollist}
466
86e78222 467\pythonnote{A tuple of values is returned in the wxPython version of
fa482912 468this method. The first value is the item id and the second is the
86e78222
RD
469flags value mentioned above.}
470
f3539882
VZ
471\perlnote{In wxPerl this method only takes the {\bf point} parameter
472 and returns a 2-element list ( item, flags ).}
473
a660d684
KB
474\membersection{wxListCtrl::InsertColumn}\label{wxlistctrlinsertcolumn}
475
eaaa6a06 476\func{long}{InsertColumn}{\param{long }{col}, \param{wxListItem\& }{info}}
a660d684
KB
477
478For list view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
479
eaaa6a06
JS
480\func{long}{InsertColumn}{\param{long }{col}, \param{const wxString\& }{heading}, \param{int }{format = wxLIST\_FORMAT\_LEFT},\rtfsp
481\param{int }{width = -1}}
a660d684
KB
482
483For list view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
484
21f280f4
RD
485\pythonnote{In place of a single overloaded method name, wxPython
486implements the following methods:\par
487\indented{2cm}{\begin{twocollist}
c9110876 488\twocolitem{{\bf InsertColumn(col, heading, format=wxLIST\_FORMAT\_LEFT,
21f280f4 489width=-1)}}{Creates a column using a header string only.}
c9110876 490\twocolitem{{\bf InsertColumnInfo(col, item)}}{Creates a column using a
21f280f4
RD
491wxListInfo.}
492\end{twocollist}}
493}
494
a660d684
KB
495\membersection{wxListCtrl::InsertItem}\label{wxlistctrlinsertitem}
496
497\func{long}{InsertItem}{\param{wxListItem\& }{info}}
498
499Inserts an item, returning the index of the new item if successful,
500-1 otherwise.
501
eaaa6a06 502\func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}}
a660d684
KB
503
504Inserts a string item.
505
eaaa6a06 506\func{long}{InsertItem}{\param{long }{index}, \param{int }{imageIndex}}
a660d684
KB
507
508Inserts an image item.
509
eaaa6a06 510\func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}, \param{int }{imageIndex}}
a660d684
KB
511
512Insert an image/string item.
513
884360bc
JS
514\wxheading{Parameters}
515
516\docparam{info}{wxListItem object}
517
518\docparam{index}{Index of the new item, supplied by the application}
519
520\docparam{label}{String label}
521
522\docparam{imageIndex}{index into the image list associated with this control and view style}
523
21f280f4
RD
524\pythonnote{In place of a single overloaded method name, wxPython
525implements the following methods:\par
ecf527c0 526\indented{2cm}{\begin{twocollist}\itemsep=0pt
c9110876
VS
527\twocolitem{{\bf InsertItem(item)}}{Inserts an item using a wxListItem.}
528\twocolitem{{\bf InsertStringItem(index, label)}}{Inserts a string item.}
529\twocolitem{{\bf InsertImageItem(index, imageIndex)}}{Inserts an image item.}
530\twocolitem{{\bf InsertImageStringItem(index, label, imageIndex)}}{Insert an image/string item.}
21f280f4
RD
531\end{twocollist}}
532}
533
f3539882
VZ
534\perlnote{In wxPerl there are four methods instead of a single overloaded
535method:\par
536\indented{2cm}{\begin{twocollist}
537\twocolitem{{\bf InsertItem( item )}}{Inserts a Wx::ListItem}
538\twocolitem{{\bf InsertStringItem( index, label )}}{Inserts a string item}
539\twocolitem{{\bf InsertImageItem( index, imageIndex )}}{Inserts an image item}
540\twocolitem{{\bf InsertImageStringItem( index, label, imageIndex )}}{Inserts
541 an item with a string and an image}
542\end{twocollist}
543}}
544
614391dc
VZ
545\membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}
546
547\func{virtual wxString}{OnGetItemAttr}{\param{long }{item}}
548
549This function may be overloaded in the derived class for a control with
550{\tt wxLC\_VIRTUAL} style. It should return the attribute for the
551for the specified {\tt item} or {\tt NULL} to use the default appearance
552parameters.
553
554The base class version always returns {\tt NULL}.
555
556\wxheading{See also}
557
558\helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
559\helpref{OnGetItemText}{wxlistctrlongetitemtext}
560
561\membersection{wxListCtrl::OnGetItemImage}\label{wxlistctrlongetitemimage}
562
563\func{virtual wxString}{OnGetItemImage}{\param{long }{item}}
564
565This function may be overloaded in the derived class for a control with
566{\tt wxLC\_VIRTUAL} style. It should return the index of the items image in the
567controls image list or $-1$ for no image.
568
569The base class version always returns $-1$.
570
571\wxheading{See also}
572
573\helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
574\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
575
576\membersection{wxListCtrl::OnGetItemText}\label{wxlistctrlongetitemtext}
577
578\func{virtual wxString}{OnGetItemText}{\param{long }{item}, \param{long }{column}}
579
580This function {\bf must} be overloaded in the derived class for a control with
581{\tt wxLC\_VIRTUAL} style. It should return the string containing the text of
582the given {\it column} for the specified {\tt item}.
583
584\wxheading{See also}
585
586\helpref{SetItemCount}{wxlistctrlsetitemcount},\\
587\helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
588\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
589
a660d684
KB
590\membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}
591
eaaa6a06 592\func{bool}{ScrollList}{\param{int }{dx}, \param{int }{dy}}
a660d684
KB
593
594Scrolls the list control. If in icon, small icon or report view mode,
595dx specifies the number of pixels to scroll. If in list view mode, dx
596specifies the number of columns to scroll.
597
598If in icon, small icon or list view mode, dy specifies the number of pixels
599to scroll. If in report view mode, dy specifies the number of lines to scroll.
600
601\membersection{wxListCtrl::SetBackgroundColour}\label{wxlistctrlsetbackgroundcolour}
602
603\func{void}{SetBackgroundColour}{\param{const wxColour\& }{col}}
604
605Sets the background colour (GetBackgroundColour already implicit in
606wxWindow class).
607
608\membersection{wxListCtrl::SetColumn}\label{wxlistctrlsetcolumn}
609
eaaa6a06 610\func{bool}{SetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
a660d684
KB
611
612Sets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
613information.
614
615\membersection{wxListCtrl::SetColumnWidth}\label{wxlistctrlsetcolumnwidth}
616
eaaa6a06 617\func{bool}{SetColumnWidth}{\param{int }{col}, \param{int }{width}}
a660d684 618
884360bc 619Sets the column width.
a660d684
KB
620
621{\it width} can be a width in pixels or wxLIST\_AUTOSIZE (-1) or wxLIST\_AUTOSIZE\_USEHEADER (-2).
0180dad6
RR
622wxLIST\_AUTOSIZE will resize the column to the length of its longest item. wxLIST\_AUTOSIZE\_USEHEADER
623will resize the column to the length of the header (Win32) or 80 pixels (other platforms).
884360bc
JS
624
625In small or normal icon view, {\it col} must be -1, and the column width is set for all columns.
a660d684
KB
626
627\membersection{wxListCtrl::SetImageList}\label{wxlistctrlsetimagelist}
628
eaaa6a06 629\func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
a660d684
KB
630
631Sets the image list associated with the control. {\it which} is one of
632wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).
633
2e12c11a
VS
634This method does not take ownership of the image list, you have to
635delete it yourself.
636
637\wxheading{See also}
638
639\helpref{wxListCtrl::AssignImageList}{wxlistctrlassignimagelist}
640
641
a660d684
KB
642\membersection{wxListCtrl::SetItem}\label{wxlistctrlsetitem}
643
644\func{bool}{SetItem}{\param{wxListItem\& }{info}}
645
2cb20bea
VS
646\func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const }{wxString\& label}, \param{int }{imageId = -1}}
647
a660d684
KB
648Sets information about the item.
649
650wxListItem is a class with the following members:
651
652\twocolwidtha{5cm}
653\begin{twocollist}\itemsep=0pt
654\twocolitem{long m\_mask}{Indicates which fields are valid. See the list of valid mask flags below.}
655\twocolitem{long m\_itemId}{The zero-based item position.}
656\twocolitem{int m\_col}{Zero-based column, if in report mode.}
657\twocolitem{long m\_state}{The state of the item. See the list of valid state flags below.}
658\twocolitem{long m\_stateMask}{A mask indicating which state flags are valid. See the list of valid state flags below.}
659\twocolitem{wxString m\_text}{The label/header text.}
660\twocolitem{int m\_image}{The zero-based index into an image list.}
661\twocolitem{long m\_data}{Application-defined data.}
662\twocolitem{int m\_format}{For columns only: the format. Can be wxLIST\_FORMAT\_LEFT, wxLIST\_FORMAT\_RIGHT or
663wxLIST\_FORMAT\_CENTRE.}
664\twocolitem{int m\_width}{For columns only: the column width.}
665\end{twocollist}
666
667The {\bf m\_mask} member contains a bitlist specifying which of the other fields are valid. The flags are:
668
669\twocolwidtha{5cm}
670\begin{twocollist}\itemsep=0pt
671\twocolitem{wxLIST\_MASK\_STATE}{The {\bf m\_state} field is valid.}
672\twocolitem{wxLIST\_MASK\_TEXT}{The {\bf m\_text} field is valid.}
673\twocolitem{wxLIST\_MASK\_IMAGE}{The {\bf m\_image} field is valid.}
674\twocolitem{wxLIST\_MASK\_DATA}{The {\bf m\_data} field is valid.}
675\twocolitem{wxLIST\_MASK\_WIDTH}{The {\bf m\_width} field is valid.}
676\twocolitem{wxLIST\_MASK\_FORMAT}{The {\bf m\_format} field is valid.}
677\end{twocollist}
678
679The {\bf m\_stateMask} and {\bf m\_state} members take flags from the following:
680
0530737d
VZ
681The wxListItem object can also contain item-specific colour and font
682information: for this you need to call one of SetTextColour(),
683SetBackgroundColour() or SetFont() functions on it passing it the colour/font
684to use. If the colour/font is not specified, the default list control
685colour/font is used.
686
a660d684
KB
687\twocolwidtha{5cm}
688\begin{twocollist}\itemsep=0pt
0180dad6
RR
689\twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is. Win32 only. }
690\twocolitem{wxLIST\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event. Win32 only. }
a660d684
KB
691\twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
692\twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
0180dad6 693\twocolitem{wxLIST\_STATE\_CUT}{The item is in the cut state. Win32 only. }
a660d684
KB
694\end{twocollist}
695
eaaa6a06 696\func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const wxString\& }{label}, \param{int }{imageId = -1}}
a660d684
KB
697
698Sets a string field at a particular column.
699
21f280f4
RD
700\pythonnote{In place of a single overloaded method name, wxPython
701implements the following methods:\par
702\indented{2cm}{\begin{twocollist}
c9110876
VS
703\twocolitem{{\bf SetItem(item)}}{Sets information about the given wxListItem.}
704\twocolitem{{\bf SetStringItem(index, col, label, imageId)}}{Sets a
21f280f4
RD
705string or image at a given location.}
706\end{twocollist}}
707}
708
614391dc
VZ
709\membersection{wxListCtrl::SetItemCount}\label{wxlistctrlsetitemcount}
710
711\func{void}{SetItemCount}{\param{long }{count}}
712
713This method can only be used with virtual list controls. It is used to indicate
714to the control the number of items it contains. After calling it, the main
715program should be ready to handle calls to various item callbacks (such as
716\helpref{OnGetItemText}{wxlistctrlongetitemtext}) for all vitems in the range
717from $0$ to {\it count}.
718
a660d684
KB
719\membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}
720
eaaa6a06 721\func{bool}{SetItemData}{\param{long }{item}, \param{long }{data}}
a660d684
KB
722
723Associates application-defined data with this item.
724
725\membersection{wxListCtrl::SetItemImage}\label{wxlistctrlsetitemimage}
726
eaaa6a06 727\func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}, \param{int }{selImage}}
a660d684
KB
728
729Sets the unselected and selected images associated with the item. The images are indices into the
730image list associated with the list control.
731
732\membersection{wxListCtrl::SetItemPosition}\label{wxlistctrlsetitemposition}
733
eaaa6a06 734\func{bool}{SetItemPosition}{\param{long }{item}, \param{const wxPoint\& }{pos}}
a660d684
KB
735
736Sets the position of the item, in icon or small icon view.
737
738\membersection{wxListCtrl::SetItemState}\label{wxlistctrlsetitemstate}
739
eaaa6a06 740\func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}}
a660d684
KB
741
742Sets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
743
744The {\bf stateMask} indicates which state flags are valid.
745
746\membersection{wxListCtrl::SetItemText}\label{wxlistctrlsetitemtext}
747
eaaa6a06 748\func{void}{SetItemText}{\param{long }{item}, \param{const wxString\& }{text}}
a660d684
KB
749
750Sets the item text for this item.
751
752\membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle}
753
eaaa6a06 754\func{void}{SetSingleStyle}{\param{long }{style}, \param{const bool }{add = TRUE}}
a660d684
KB
755
756Adds or removes a single window style.
757
758\membersection{wxListCtrl::SetTextColour}\label{wxlistctrlsettextcolour}
759
760\func{void}{SetTextColour}{\param{const wxColour\& }{col}}
761
762Sets the text colour of the list control.
763
764\membersection{wxListCtrl::SetWindowStyleFlag}\label{wxlistctrlsetwindowstyleflag}
765
eaaa6a06 766\func{void}{SetWindowStyleFlag}{\param{long }{style}}
a660d684
KB
767
768Sets the whole window style.
769
770\membersection{wxListCtrl::SortItems}\label{wxlistctrlsortitems}
771
963863ad 772\func{bool}{SortItems}{\param{wxListCtrlCompare }{fnSortCallBack}, \param{long }{data}}
a660d684 773
aa9fb2be 774Call this function to sort the items in the list control. Sorting is done
963863ad
VZ
775using the specified {\it fnSortCallBack} function. This function must have the
776following prototype:
a660d684 777
963863ad
VZ
778\begin{verbatim}
779int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
780\end{verbatim}
a660d684 781
963863ad
VZ
782It is called each time when the two items must be compared and should return 0
783if the items are equal, negative value if the first item is less than the
784second one and positive value if the first one is greater than the second one
785(the same convention as used by {\tt qsort(3)}).
a660d684 786
963863ad 787\wxheading{Parameters}
a660d684 788
ecf527c0 789\docparam{item1}{client data associated with the first item ({\bf NOT} the index).}
aa9fb2be 790
ecf527c0 791\docparam{item2}{client data associated with the second item ({\bf NOT} the index).}
aa9fb2be 792
963863ad 793\docparam{data}{the value passed to SortItems() itself.}
a660d684 794
963863ad
VZ
795Notice that the control may only be sorted on client data associated with the
796items, so you {\bf must} use \helpref{SetItemData}{wxlistctrlsetitemdata} if
797you want to be able to sort the items in the control.
a660d684 798
963863ad
VZ
799Please see the \helpref{listctrl sample}{samplelistctrl} for an example of
800using this function.
ecf527c0 801
aa9fb2be
RD
802\pythonnote{wxPython uses the sortData parameter to pass the Python
803function to call, so it is not available for programmer use. Call
804SortItems with a reference to a callable object that expects two
805parameters.}
281b0186 806
f3539882
VZ
807\perlnote{In wxPerl the comparison function must take just two parameters;
808 however, you may use a closure to achieve an effect similar to the
809 SortItems third parameter.}
810