]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/listctrl.tex
Build fix after DrawPushButton introduction.
[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.
257
258 \func{long}{FindItem}{\param{long }{start}, \param{long }{data}}
259
260 Find an item whose data matches this data, starting from {\it start} or
261 the beginning if 'start' is -1.
262
263 \func{long}{FindItem}{\param{long }{start}, \param{const wxPoint\& }{pt}, \param{int }{direction}}
264
265 Find an item nearest this position in the specified direction, starting from
266 {\it start} or the beginning if {\it start} is -1.
267
268 \pythonnote{In place of a single overloaded method name, wxPython
269 implements the following methods:\par
270 \indented{2cm}{\begin{twocollist}
271 \twocolitem{{\bf FindItem(start, str, partial=false)}}{}
272 \twocolitem{{\bf FindItemData(start, data)}}{}
273 \twocolitem{{\bf FindItemAtPos(start, point, direction)}}{}
274 \end{twocollist}}
275 }
276
277 \perlnote{In wxPerl there are three methods instead of a single overloaded
278 method:\par
279 \indented{2cm}{\begin{twocollist}
280 \twocolitem{{\bf FindItem( start, str, partial = false ) }}{}
281 \twocolitem{{\bf FindItemData( start, data ) }}{}
282 \twocolitem{{\bf FindItemAtPos( start, point, direction )}}{}
283 \end{twocollist}
284 }}
285
286
287 \membersection{wxListCtrl::GetColumn}\label{wxlistctrlgetcolumn}
288
289 \constfunc{bool}{GetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
290
291 Gets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
292 information.
293
294 \perlnote{In wxPerl this method takes only the {\bf col} parameter and
295 returns a Wx::ListItem ( or undef ).}
296
297
298 \membersection{wxListCtrl::GetColumnCount}\label{wxlistctrlgetcolumncount}
299
300 \constfunc{int}{GetColumnCount}{\void}
301
302 Returns the number of columns.
303
304
305 \membersection{wxListCtrl::GetColumnWidth}\label{wxlistctrlgetcolumnwidth}
306
307 \constfunc{int}{GetColumnWidth}{\param{int }{col}}
308
309 Gets the column width (report view only).
310
311
312 \membersection{wxListCtrl::GetCountPerPage}\label{wxlistctrlgetcountperpage}
313
314 \constfunc{int}{GetCountPerPage}{\void}
315
316 Gets the number of items that can fit vertically in the
317 visible area of the list control (list or report view)
318 or the total number of items in the list control (icon
319 or small icon view).
320
321
322 \membersection{wxListCtrl::GetEditControl}\label{wxlistctrlgeteditcontrol}
323
324 \constfunc{wxTextCtrl *}{GetEditControl}{\void}
325
326 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
327 if no label is being edited.
328
329 {\bf NB:} It is currently only implemented for wxMSW.
330
331
332 \membersection{wxListCtrl::GetImageList}\label{wxlistctrlgetimagelist}
333
334 \constfunc{wxImageList*}{GetImageList}{\param{int }{which}}
335
336 Returns the specified image list. {\it which} may be one of:
337
338 \twocolwidtha{5cm}
339 \begin{twocollist}\itemsep=0pt
340 \twocolitem{\windowstyle{wxIMAGE\_LIST\_NORMAL}}{The normal (large icon) image list.}
341 \twocolitem{\windowstyle{wxIMAGE\_LIST\_SMALL}}{The small icon image list.}
342 \twocolitem{\windowstyle{wxIMAGE\_LIST\_STATE}}{The user-defined state image list (unimplemented).}
343 \end{twocollist}
344
345
346 \membersection{wxListCtrl::GetItem}\label{wxlistctrlgetitem}
347
348 \constfunc{bool}{GetItem}{\param{wxListItem\& }{info}}
349
350 Gets information about the item. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
351 information.
352
353 You must call {\it info.SetId()} to the ID of item you're interested in
354 before calling this method.
355
356 \pythonnote{The wxPython version of this method takes an integer parameter
357 for the item ID, an optional integer for the column number, and
358 returns the wxListItem object.}
359
360 \perlnote{In wxPerl this method takes as parameter the {\bf ID} of the item
361 and ( optionally ) the column, and returns a Wx::ListItem object.}
362
363
364 \membersection{wxListCtrl::GetItemBackgroundColour}\label{wxlistctrlgetitembackgroundcolour}
365
366 \constfunc{wxColour}{GetItemBackgroundColour}{\param{long }{item}}
367
368 Returns the colour for this item. If the item has no specific colour, returns
369 an invalid colour (and not the default background control of the control
370 itself).
371
372 \wxheading{See also}
373
374 \helpref{GetItemTextColour}{wxlistctrlgetitemtextcolour}
375
376
377 \membersection{wxListCtrl::GetItemCount}\label{wxlistctrlgetitemcount}
378
379 \constfunc{int}{GetItemCount}{\void}
380
381 Returns the number of items in the list control.
382
383
384 \membersection{wxListCtrl::GetItemData}\label{wxlistctrlgetitemdata}
385
386 \constfunc{long}{GetItemData}{\param{long }{item}}
387
388 Gets the application-defined data associated with this item.
389
390
391 \membersection{wxListCtrl::GetItemFont}\label{wxlistctrlgetitemfont}
392
393 \constfunc{wxFont}{GetItemFont}{\param{long }{item}}
394
395 Returns the item's font.
396
397
398 \membersection{wxListCtrl::GetItemPosition}\label{wxlistctrlgetitemposition}
399
400 \constfunc{bool}{GetItemPosition}{\param{long }{item}, \param{wxPoint\& }{pos}}
401
402 Returns the position of the item, in icon or small icon view.
403
404 \pythonnote{The wxPython version of this method accepts only the item
405 ID and returns the wxPoint.}
406
407 \perlnote{In wxPerl this method takes only the {\bf item} parameter and
408 returns a Wx::Point ( or undef ).}
409
410
411 \membersection{wxListCtrl::GetItemRect}\label{wxlistctrlgetitemrect}
412
413 \constfunc{bool}{GetItemRect}{\param{long }{item}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
414
415 Returns the rectangle representing the item's size and position, in physical
416 coordinates.
417
418 {\it code} is one of wxLIST\_RECT\_BOUNDS, wxLIST\_RECT\_ICON, wxLIST\_RECT\_LABEL.
419
420 \pythonnote{The wxPython version of this method accepts only the item
421 ID and code and returns the wxRect.}
422
423 \perlnote{In wxPerl this method takes only the {\bf item} parameter and
424 returns a Wx::Rect ( or undef ).}
425
426
427
428 \membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
429
430 \constfunc{wxSize}{GetItemSpacing}{\void}
431
432 Retrieves the spacing between icons in pixels: horizontal spacing is returned
433 as \texttt{x} component of the \helpref{wxSize}{wxsize} object and the vertical
434 spacing as its \texttt{y} component.
435
436
437
438 \membersection{wxListCtrl::GetItemState}\label{wxlistctrlgetitemstate}
439
440 \constfunc{int}{GetItemState}{\param{long }{item}, \param{long }{stateMask}}
441
442 Gets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
443
444 The {\bf stateMask} indicates which state flags are of interest.
445
446
447 \membersection{wxListCtrl::GetItemText}\label{wxlistctrlgetitemtext}
448
449 \constfunc{wxString}{GetItemText}{\param{long }{item}}
450
451 Gets the item text for this item.
452
453
454 \membersection{wxListCtrl::GetItemTextColour}\label{wxlistctrlgetitemtextcolour}
455
456 \constfunc{wxColour}{GetItemTextColour}{\param{long }{item}}
457
458 Returns the colour for this item. If the item has no specific colour, returns
459 an invalid colour (and not the default foreground control of the control itself
460 as this wouldn't allow distinguishing between items having the same colour as
461 the current control foreground and items with default colour which, hence, have
462 always the same colour as the control).
463
464
465 \membersection{wxListCtrl::GetNextItem}\label{wxlistctrlgetnextitem}
466
467 \constfunc{long}{GetNextItem}{\param{long }{item}, \param{int }{geometry = wxLIST\_NEXT\_ALL}, \param{int }{state = wxLIST\_STATE\_DONTCARE}}
468
469 Searches for an item with the given geometry or state, starting from
470 {\it item} but excluding the {\it item} itself. If {\it item} is -1,
471 the first item that matches the specified flags will be returned.
472
473 Returns the first item with given state following {\it item} or -1 if
474 no such item found.
475
476 This function may be used to find all selected items in the control like this:
477
478 \begin{verbatim}
479 long item = -1;
480 for ( ;; )
481 {
482 item = listctrl->GetNextItem(item,
483 wxLIST_NEXT_ALL,
484 wxLIST_STATE_SELECTED);
485 if ( item == -1 )
486 break;
487
488 // this item is selected - do whatever is needed with it
489 wxLogMessage("Item %ld is selected.", item);
490 }
491 \end{verbatim}
492
493 {\it geometry} can be one of:
494
495 \twocolwidtha{5cm}
496 \begin{twocollist}\itemsep=0pt
497 \twocolitem{wxLIST\_NEXT\_ABOVE}{Searches for an item above the specified item.}
498 \twocolitem{wxLIST\_NEXT\_ALL}{Searches for subsequent item by index.}
499 \twocolitem{wxLIST\_NEXT\_BELOW}{Searches for an item below the specified item.}
500 \twocolitem{wxLIST\_NEXT\_LEFT}{Searches for an item to the left of the specified item.}
501 \twocolitem{wxLIST\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.}
502 \end{twocollist}
503
504 {\bf NB:} this parameter is only supported by wxMSW currently and ignored on
505 other platforms.
506
507 {\it state} can be a bitlist of the following:
508
509 \twocolwidtha{5cm}
510 \begin{twocollist}\itemsep=0pt
511 \twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is.}
512 \twocolitem{wxLIST\_STATE\_DROPHILITED}{The item indicates it is a drop target.}
513 \twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
514 \twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
515 \twocolitem{wxLIST\_STATE\_CUT}{The item is selected as part of a cut and paste operation.}
516 \end{twocollist}
517
518
519 \membersection{wxListCtrl::GetSelectedItemCount}\label{wxlistctrlgetselecteditemcount}
520
521 \constfunc{int}{GetSelectedItemCount}{\void}
522
523 Returns the number of selected items in the list control.
524
525
526 \membersection{wxListCtrl::GetTextColour}\label{wxlistctrlgettextcolour}
527
528 \constfunc{wxColour}{GetTextColour}{\void}
529
530 Gets the text colour of the list control.
531
532
533 \membersection{wxListCtrl::GetTopItem}\label{wxlistctrlgettopitem}
534
535 \constfunc{long}{GetTopItem}{\void}
536
537 Gets the index of the topmost visible item when in
538 list or report view.
539
540
541
542 \membersection{wxListCtrl::GetViewRect}\label{wxlistctrlgetviewrect}
543
544 \constfunc{wxRect}{GetViewRect}{\void}
545
546 Returns the rectangle taken by all items in the control. In other words, if the
547 controls client size were equal to the size of this rectangle, no scrollbars
548 would be needed and no free space would be left.
549
550 Note that this function only works in the icon and small icon views, not in
551 list or report views (this is a limitation of the native Win32 control).
552
553
554
555 \membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
556
557 \func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
558
559 Determines which item (if any) is at the specified point,
560 giving details in {\it flags}. Returns index of the item or {\tt wxNOT\_FOUND}
561 if no item is at the specified point.
562 {\it flags} will be a combination of the following flags:
563
564 \twocolwidtha{5cm}
565 \begin{twocollist}\itemsep=0pt
566 \twocolitem{wxLIST\_HITTEST\_ABOVE}{Above the client area.}
567 \twocolitem{wxLIST\_HITTEST\_BELOW}{Below the client area.}
568 \twocolitem{wxLIST\_HITTEST\_NOWHERE}{In the client area but below the last item.}
569 \twocolitem{wxLIST\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
570 \twocolitem{wxLIST\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
571 \twocolitem{wxLIST\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
572 \twocolitem{wxLIST\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
573 \twocolitem{wxLIST\_HITTEST\_TOLEFT}{To the right of the client area.}
574 \twocolitem{wxLIST\_HITTEST\_TORIGHT}{To the left of the client area.}
575 \twocolitem{wxLIST\_HITTEST\_ONITEM}{Combination of wxLIST\_HITTEST\_ONITEMICON, wxLIST\_HITTEST\_ONITEMLABEL,
576 wxLIST\_HITTEST\_ONITEMSTATEICON.}
577 \end{twocollist}
578
579 \pythonnote{A tuple of values is returned in the wxPython version of
580 this method. The first value is the item id and the second is the
581 flags value mentioned above.}
582
583 \perlnote{In wxPerl this method only takes the {\bf point} parameter
584 and returns a 2-element list {\tt ( item, flags )}.}
585
586
587 \membersection{wxListCtrl::InsertColumn}\label{wxlistctrlinsertcolumn}
588
589 \func{long}{InsertColumn}{\param{long }{col}, \param{wxListItem\& }{info}}
590
591 \func{long}{InsertColumn}{\param{long }{col}, \param{const wxString\& }{heading}, \param{int }{format = wxLIST\_FORMAT\_LEFT},\rtfsp
592 \param{int }{width = -1}}
593
594 For report view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
595
596 \pythonnote{In place of a single overloaded method name, wxPython
597 implements the following methods:\par
598 \indented{2cm}{\begin{twocollist}
599 \twocolitem{{\bf InsertColumn(col, heading, format=wxLIST\_FORMAT\_LEFT,
600 width=-1)}}{Creates a column using a header string only.}
601 \twocolitem{{\bf InsertColumnItem(col, item)}}{Creates a column using a
602 wxListItem.}
603 \end{twocollist}}
604 }
605
606
607 \membersection{wxListCtrl::InsertItem}\label{wxlistctrlinsertitem}
608
609 \func{long}{InsertItem}{\param{wxListItem\& }{info}}
610
611 Inserts an item, returning the index of the new item if successful,
612 -1 otherwise.
613
614 \func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}}
615
616 Inserts a string item.
617
618 \func{long}{InsertItem}{\param{long }{index}, \param{int }{imageIndex}}
619
620 Inserts an image item.
621
622 \func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}, \param{int }{imageIndex}}
623
624 Insert an image/string item.
625
626 \wxheading{Parameters}
627
628 \docparam{info}{wxListItem object}
629
630 \docparam{index}{Index of the new item, supplied by the application}
631
632 \docparam{label}{String label}
633
634 \docparam{imageIndex}{index into the image list associated with this control and view style}
635
636 \pythonnote{In place of a single overloaded method name, wxPython
637 implements the following methods:\par
638 \indented{2cm}{\begin{twocollist}\itemsep=0pt
639 \twocolitem{{\bf InsertItem(item)}}{Inserts an item using a wxListItem.}
640 \twocolitem{{\bf InsertStringItem(index, label)}}{Inserts a string item.}
641 \twocolitem{{\bf InsertImageItem(index, imageIndex)}}{Inserts an image item.}
642 \twocolitem{{\bf InsertImageStringItem(index, label, imageIndex)}}{Insert an image/string item.}
643 \end{twocollist}}
644 }
645
646 \perlnote{In wxPerl there are four methods instead of a single overloaded
647 method:\par
648 \indented{2cm}{\begin{twocollist}
649 \twocolitem{{\bf InsertItem( item )}}{Inserts a Wx::ListItem}
650 \twocolitem{{\bf InsertStringItem( index, label )}}{Inserts a string item}
651 \twocolitem{{\bf InsertImageItem( index, imageIndex )}}{Inserts an image item}
652 \twocolitem{{\bf InsertImageStringItem( index, label, imageIndex )}}{Inserts
653 an item with a string and an image}
654 \end{twocollist}
655 }}
656
657
658 \membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}
659
660 \constfunc{virtual wxListItemAttr *}{OnGetItemAttr}{\param{long }{item}}
661
662 This function may be overloaded in the derived class for a control with
663 {\tt wxLC\_VIRTUAL} style. It should return the attribute for the
664 for the specified {\tt item} or {\tt NULL} to use the default appearance
665 parameters.
666
667 wxListCtrl will not delete the pointer or keep a reference of it. You can
668 return the same wxListItemAttr pointer for every OnGetItemAttr call.
669
670 The base class version always returns {\tt NULL}.
671
672 \wxheading{See also}
673
674 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
675 \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
676 \helpref{OnGetItemText}{wxlistctrlongetitemtext}
677
678
679 \membersection{wxListCtrl::OnGetItemImage}\label{wxlistctrlongetitemimage}
680
681 \constfunc{virtual int}{OnGetItemImage}{\param{long }{item}}
682
683 This function must be overloaded in the derived class for a control with
684 {\tt wxLC\_VIRTUAL} style having an \helpref{image list}{wxlistctrlsetimagelist}
685 (if the control doesn't have an image list, it is not necessary to overload
686 it). It should return the index of the items image in the controls image list
687 or $-1$ for no image.
688 In a control with {\tt wxLC\_REPORT} style, OnGetItemImage only gets called for
689 the first column of each line.
690
691 The base class version always returns $-1$.
692
693 \wxheading{See also}
694
695 \helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
696 \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
697 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
698
699 \membersection{wxListCtrl::OnGetItemColumnImage}\label{wxlistctrlongetitemcolumnimage}
700
701 \constfunc{virtual int}{OnGetItemColumnImage}{\param{long }{item}, \param{long }{column}}
702
703 Overload this function in the derived class for a control with
704 {\tt wxLC\_VIRTUAL} and {\tt wxLC\_REPORT} styles in order to specify the image
705 index for the given line and column.
706
707 The base class version always calls OnGetItemImage for the first column, else
708 it returns $-1$.
709
710 \wxheading{See also}
711
712 \helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
713 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
714 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
715
716 \membersection{wxListCtrl::OnGetItemText}\label{wxlistctrlongetitemtext}
717
718 \constfunc{virtual wxString}{OnGetItemText}{\param{long }{item}, \param{long }{column}}
719
720 This function {\bf must} be overloaded in the derived class for a control with
721 {\tt wxLC\_VIRTUAL} style. It should return the string containing the text of
722 the given {\it column} for the specified {\tt item}.
723
724 \wxheading{See also}
725
726 \helpref{SetItemCount}{wxlistctrlsetitemcount},\\
727 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
728 \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
729 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
730
731
732 \membersection{wxListCtrl::RefreshItem}\label{wxlistctrlrefreshitem}
733
734 \func{void}{RefreshItem}{\param{long }{item}}
735
736 Redraws the given {\it item}. This is only useful for the virtual list controls
737 as without calling this function the displayed value of the item doesn't change
738 even when the underlying data does change.
739
740 \wxheading{See also}
741
742 \helpref{RefreshItems}{wxlistctrlrefreshitems}
743
744
745
746 \membersection{wxListCtrl::RefreshItems}\label{wxlistctrlrefreshitems}
747
748 \func{void}{RefreshItems}{\param{long }{itemFrom}, \param{long }{itemTo}}
749
750 Redraws the items between {\it itemFrom} and {\it itemTo}. The starting item
751 must be less than or equal to the ending one.
752
753 Just as \helpref{RefreshItem}{wxlistctrlrefreshitem} this is only useful for
754 virtual list controls.
755
756
757
758 \membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}
759
760 \func{bool}{ScrollList}{\param{int }{dx}, \param{int }{dy}}
761
762 Scrolls the list control. If in icon, small icon or report view mode,
763 {\it dx} specifies the number of pixels to scroll. If in list view mode,
764 {\it dx} specifies the number of columns to scroll. {\it dy} always specifies
765 the number of pixels to scroll vertically.
766
767 {\bf NB:} This method is currently only implemented in the Windows version.
768
769
770 \membersection{wxListCtrl::SetBackgroundColour}\label{wxlistctrlsetbackgroundcolour}
771
772 \func{void}{SetBackgroundColour}{\param{const wxColour\& }{col}}
773
774 Sets the background colour (GetBackgroundColour already implicit in
775 wxWindow class).
776
777
778 \membersection{wxListCtrl::SetColumn}\label{wxlistctrlsetcolumn}
779
780 \func{bool}{SetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
781
782 Sets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
783 information.
784
785
786 \membersection{wxListCtrl::SetColumnWidth}\label{wxlistctrlsetcolumnwidth}
787
788 \func{bool}{SetColumnWidth}{\param{int }{col}, \param{int }{width}}
789
790 Sets the column width.
791
792 {\it width} can be a width in pixels or wxLIST\_AUTOSIZE (-1) or wxLIST\_AUTOSIZE\_USEHEADER (-2).
793 wxLIST\_AUTOSIZE will resize the column to the length of its longest item. wxLIST\_AUTOSIZE\_USEHEADER
794 will resize the column to the length of the header (Win32) or 80 pixels (other platforms).
795
796 In small or normal icon view, {\it col} must be -1, and the column width is set for all columns.
797
798
799 \membersection{wxListCtrl::SetImageList}\label{wxlistctrlsetimagelist}
800
801 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
802
803 Sets the image list associated with the control. {\it which} is one of
804 wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).
805
806 This method does not take ownership of the image list, you have to
807 delete it yourself.
808
809 \wxheading{See also}
810
811 \helpref{wxListCtrl::AssignImageList}{wxlistctrlassignimagelist}
812
813
814
815 \membersection{wxListCtrl::SetItem}\label{wxlistctrlsetitem}
816
817 \func{bool}{SetItem}{\param{wxListItem\& }{info}}
818
819 \func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const }{wxString\& label}, \param{int }{imageId = -1}}
820
821 Sets information about the item.
822
823 wxListItem is a class with the following members:
824
825 \twocolwidtha{5cm}
826 \begin{twocollist}\itemsep=0pt
827 \twocolitem{long m\_mask}{Indicates which fields are valid. See the list of valid mask flags below.}
828 \twocolitem{long m\_itemId}{The zero-based item position.}
829 \twocolitem{int m\_col}{Zero-based column, if in report mode.}
830 \twocolitem{long m\_state}{The state of the item. See the list of valid state flags below.}
831 \twocolitem{long m\_stateMask}{A mask indicating which state flags are valid. See the list of valid state flags below.}
832 \twocolitem{wxString m\_text}{The label/header text.}
833 \twocolitem{int m\_image}{The zero-based index into an image list.}
834 \twocolitem{long m\_data}{Application-defined data.}
835 \twocolitem{int m\_format}{For columns only: the format. Can be wxLIST\_FORMAT\_LEFT, wxLIST\_FORMAT\_RIGHT or
836 wxLIST\_FORMAT\_CENTRE.}
837 \twocolitem{int m\_width}{For columns only: the column width.}
838 \end{twocollist}
839
840 The {\bf m\_mask} member contains a bitlist specifying which of the other fields are valid. The flags are:
841
842 \twocolwidtha{5cm}
843 \begin{twocollist}\itemsep=0pt
844 \twocolitem{wxLIST\_MASK\_STATE}{The {\bf m\_state} field is valid.}
845 \twocolitem{wxLIST\_MASK\_TEXT}{The {\bf m\_text} field is valid.}
846 \twocolitem{wxLIST\_MASK\_IMAGE}{The {\bf m\_image} field is valid.}
847 \twocolitem{wxLIST\_MASK\_DATA}{The {\bf m\_data} field is valid.}
848 \twocolitem{wxLIST\_MASK\_WIDTH}{The {\bf m\_width} field is valid.}
849 \twocolitem{wxLIST\_MASK\_FORMAT}{The {\bf m\_format} field is valid.}
850 \end{twocollist}
851
852 The {\bf m\_stateMask} and {\bf m\_state} members take flags from the following:
853
854 \twocolwidtha{5cm}
855 \begin{twocollist}\itemsep=0pt
856 \twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is. Win32 only. }
857 \twocolitem{wxLIST\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event. Win32 only. }
858 \twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
859 \twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
860 \twocolitem{wxLIST\_STATE\_CUT}{The item is in the cut state. Win32 only. }
861 \end{twocollist}
862
863 The wxListItem object can also contain item-specific colour and font
864 information: for this you need to call one of SetTextColour(),
865 SetBackgroundColour() or SetFont() functions on it passing it the colour/font
866 to use. If the colour/font is not specified, the default list control
867 colour/font is used.
868
869 \func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const wxString\& }{label}, \param{int }{imageId = -1}}
870
871 Sets a string field at a particular column.
872
873 \pythonnote{In place of a single overloaded method name, wxPython
874 implements the following methods:\par
875 \indented{2cm}{\begin{twocollist}
876 \twocolitem{{\bf SetItem(item)}}{Sets information about the given wxListItem.}
877 \twocolitem{{\bf SetStringItem(index, col, label, imageId)}}{Sets a
878 string or image at a given location.}
879 \end{twocollist}}
880 }
881
882 \membersection{wxListCtrl::SetItemBackgroundColour}\label{wxlistctrlsetitembackgroundcolour}
883
884 \func{void}{SetItemBackgroundColour}{\param{long }{item}, \param{const wxColour\& }{col}}
885
886 Sets the background colour for this item. This function only works in report view.
887
888 The colour can be retrieved using
889 \helpref{GetItemBackgroundColour}{wxlistctrlgetitembackgroundcolour}.
890
891
892
893 \membersection{wxListCtrl::SetItemCount}\label{wxlistctrlsetitemcount}
894
895 \func{void}{SetItemCount}{\param{long }{count}}
896
897 This method can only be used with virtual list controls. It is used to indicate
898 to the control the number of items it contains. After calling it, the main
899 program should be ready to handle calls to various item callbacks (such as
900 \helpref{OnGetItemText}{wxlistctrlongetitemtext}) for all items in the range
901 from $0$ to {\it count}.
902
903
904 \membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}
905
906 \func{bool}{SetItemData}{\param{long }{item}, \param{long }{data}}
907
908 Associates application-defined data with this item.
909
910
911 \membersection{wxListCtrl::SetItemFont}\label{wxlistctrlsetitemfont}
912
913 \func{void}{SetItemFont}{\param{long }{item}, \param{const wxFont\& }{font}}
914
915 Sets the item's font.
916
917
918 \membersection{wxListCtrl::SetItemImage}\label{wxlistctrlsetitemimage}
919
920 \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}}
921
922 Sets the image associated with the item. The image is an index into the
923 image list associated with the list control. In report view, this only sets
924 the image for the first column.
925
926 \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}, \param{int }{selImage}}
927
928 Sets the unselected and selected images associated with the item. The images are indices into the
929 image list associated with the list control. This form is deprecated: {\it selImage} is not
930 used.
931
932
933 \membersection{wxListCtrl::SetItemColumnImage}\label{wxlistctrlsetitemcolumnimage}
934
935 \func{bool}{SetItemImage}{\param{long }{item}, \param{long }{column}\param{int }{image}}
936
937 Sets the image associated with the item. In report view, you can specify the column.
938 The image is an index into the image list associated with the list control.
939
940
941 \membersection{wxListCtrl::SetItemPosition}\label{wxlistctrlsetitemposition}
942
943 \func{bool}{SetItemPosition}{\param{long }{item}, \param{const wxPoint\& }{pos}}
944
945 Sets the position of the item, in icon or small icon view. Windows only.
946
947
948 \membersection{wxListCtrl::SetItemState}\label{wxlistctrlsetitemstate}
949
950 \func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}}
951
952 Sets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
953
954 The {\bf stateMask} indicates which state flags are valid.
955
956
957 \membersection{wxListCtrl::SetItemText}\label{wxlistctrlsetitemtext}
958
959 \func{void}{SetItemText}{\param{long }{item}, \param{const wxString\& }{text}}
960
961 Sets the item text for this item.
962
963
964 \membersection{wxListCtrl::SetItemTextColour}\label{wxlistctrlsetitemtextcolour}
965
966 \func{void}{SetItemTextColour}{\param{long }{item}, \param{const wxColour\& }{col}}
967
968 Sets the colour for this item. This function only works in report view.
969
970 The colour can be retrieved using
971 \helpref{GetItemTextColour}{wxlistctrlgetitemtextcolour}.
972
973
974 \membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle}
975
976 \func{void}{SetSingleStyle}{\param{long }{style}, \param{const bool }{add = true}}
977
978 Adds or removes a single window style.
979
980
981 \membersection{wxListCtrl::SetTextColour}\label{wxlistctrlsettextcolour}
982
983 \func{void}{SetTextColour}{\param{const wxColour\& }{col}}
984
985 Sets the text colour of the list control.
986
987
988 \membersection{wxListCtrl::SetWindowStyleFlag}\label{wxlistctrlsetwindowstyleflag}
989
990 \func{void}{SetWindowStyleFlag}{\param{long }{style}}
991
992 Sets the whole window style, deleting all items.
993
994 \membersection{wxListCtrl::SortItems}\label{wxlistctrlsortitems}
995
996 \func{bool}{SortItems}{\param{wxListCtrlCompare }{fnSortCallBack}, \param{long }{data}}
997
998 Call this function to sort the items in the list control. Sorting is done
999 using the specified {\it fnSortCallBack} function. This function must have the
1000 following prototype:
1001
1002 \begin{verbatim}
1003 int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
1004 \end{verbatim}
1005
1006 It is called each time when the two items must be compared and should return 0
1007 if the items are equal, negative value if the first item is less than the
1008 second one and positive value if the first one is greater than the second one
1009 (the same convention as used by {\tt qsort(3)}).
1010
1011 \wxheading{Parameters}
1012
1013 \docparam{item1}{client data associated with the first item ({\bf NOT} the index).}
1014
1015 \docparam{item2}{client data associated with the second item ({\bf NOT} the index).}
1016
1017 \docparam{data}{the value passed to SortItems() itself.}
1018
1019 Notice that the control may only be sorted on client data associated with the
1020 items, so you {\bf must} use \helpref{SetItemData}{wxlistctrlsetitemdata} if
1021 you want to be able to sort the items in the control.
1022
1023 Please see the \helpref{listctrl sample}{samplelistctrl} for an example of
1024 using this function.
1025
1026 \pythonnote{wxPython uses the sortData parameter to pass the Python
1027 function to call, so it is not available for programmer use. Call
1028 SortItems with a reference to a callable object that expects two
1029 parameters.}
1030
1031 \perlnote{In wxPerl the comparison function must take just two parameters;
1032 however, you may use a closure to achieve an effect similar to the
1033 SortItems third parameter.}
1034