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