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