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