Commit | Line | Data |
---|---|---|
23324ae1 | 1 | ///////////////////////////////////////////////////////////////////////////// |
80cc5fc7 | 2 | // Name: wx/listctrl.h |
e54c96f1 | 3 | // Purpose: interface of wxListCtrl |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
9 | /** | |
10 | @class wxListCtrl | |
7c913512 | 11 | |
23324ae1 FM |
12 | A list control presents lists in a number of formats: list view, report view, |
13 | icon view and small icon view. In any case, elements are numbered from zero. | |
14 | For all these modes, the items are stored in the control and must be added to | |
15 | it using wxListCtrl::InsertItem method. | |
7c913512 | 16 | |
23324ae1 FM |
17 | A special case of report view quite different from the other modes of the list |
18 | control is a virtual control in which the items data (including text, images | |
19 | and attributes) is managed by the main program and is requested by the control | |
20 | itself only when needed which allows to have controls with millions of items | |
21 | without consuming much memory. To use virtual list control you must use | |
75504144 | 22 | wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText |
320ab87c FM |
23 | (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and |
24 | wxListCtrl::OnGetItemAttr) to return the information about the items when the | |
25 | control requests it. | |
5bcb6a69 | 26 | |
320ab87c FM |
27 | Virtual list control can be used as a normal one except that no operations |
28 | which can take time proportional to the number of items in the control happen | |
29 | -- this is required to allow having a practically infinite number of items. | |
30 | For example, in a multiple selection virtual list control, the selections won't | |
31 | be sent when many items are selected at once because this could mean iterating | |
32 | over all the items. | |
7c913512 | 33 | |
23324ae1 | 34 | Using many of wxListCtrl features is shown in the |
320ab87c | 35 | @ref page_samples_listctrl "corresponding sample". |
7c913512 | 36 | |
23324ae1 FM |
37 | To intercept events from a list control, use the event table macros described |
38 | in wxListEvent. | |
7c913512 | 39 | |
320ab87c FM |
40 | <b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native |
41 | implementation for report mode, and uses a generic implementation for other | |
42 | modes. You can use the generic implementation for report mode as well by setting | |
5bcb6a69 | 43 | the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1. |
2e2b4d24 | 44 | |
7c913512 | 45 | |
23324ae1 | 46 | @beginStyleTable |
8c6791e4 | 47 | @style{wxLC_LIST} |
23324ae1 FM |
48 | Multicolumn list view, with optional small icons. Columns are |
49 | computed automatically, i.e. you don't set columns as in | |
5bcb6a69 | 50 | @c wxLC_REPORT. In other words, the list wraps, unlike a wxListBox. |
8c6791e4 | 51 | @style{wxLC_REPORT} |
23324ae1 | 52 | Single or multicolumn report view, with optional header. |
8c6791e4 | 53 | @style{wxLC_VIRTUAL} |
23324ae1 | 54 | The application provides items text on demand. May only be used |
5bcb6a69 | 55 | with @c wxLC_REPORT. |
8c6791e4 | 56 | @style{wxLC_ICON} |
23324ae1 | 57 | Large icon view, with optional labels. |
8c6791e4 | 58 | @style{wxLC_SMALL_ICON} |
23324ae1 | 59 | Small icon view, with optional labels. |
8c6791e4 | 60 | @style{wxLC_ALIGN_TOP} |
23324ae1 | 61 | Icons align to the top. Win32 default, Win32 only. |
8c6791e4 | 62 | @style{wxLC_ALIGN_LEFT} |
23324ae1 | 63 | Icons align to the left. |
8c6791e4 | 64 | @style{wxLC_AUTOARRANGE} |
23324ae1 | 65 | Icons arrange themselves. Win32 only. |
8c6791e4 | 66 | @style{wxLC_EDIT_LABELS} |
23324ae1 FM |
67 | Labels are editable: the application will be notified when editing |
68 | starts. | |
8c6791e4 | 69 | @style{wxLC_NO_HEADER} |
23324ae1 | 70 | No header in report mode. |
8c6791e4 | 71 | @style{wxLC_SINGLE_SEL} |
23324ae1 | 72 | Single selection (default is multiple). |
8c6791e4 | 73 | @style{wxLC_SORT_ASCENDING} |
b45506e8 VZ |
74 | Sort in ascending order. (You must still supply a comparison callback |
75 | in wxListCtrl::SortItems.) | |
8c6791e4 | 76 | @style{wxLC_SORT_DESCENDING} |
b45506e8 VZ |
77 | Sort in descending order. (You must still supply a comparison callback |
78 | in wxListCtrl::SortItems.) | |
8c6791e4 | 79 | @style{wxLC_HRULES} |
23324ae1 | 80 | Draws light horizontal rules between rows in report mode. |
8c6791e4 | 81 | @style{wxLC_VRULES} |
23324ae1 FM |
82 | Draws light vertical rules between columns in report mode. |
83 | @endStyleTable | |
7c913512 | 84 | |
2e2b4d24 | 85 | |
3051a44a | 86 | @beginEventEmissionTable{wxListEvent} |
2e2b4d24 RR |
87 | @event{EVT_LIST_BEGIN_DRAG(id, func)} |
88 | Begin dragging with the left mouse button. | |
232fdc63 | 89 | Processes a @c wxEVT_COMMAND_LIST_BEGIN_DRAG event type. |
2e2b4d24 | 90 | @event{EVT_LIST_BEGIN_RDRAG(id, func)} |
232fdc63 VZ |
91 | Begin dragging with the right mouse button. |
92 | Processes a @c wxEVT_COMMAND_LIST_BEGIN_RDRAG event type. | |
93 | @event{EVT_BEGIN_LABEL_EDIT(id, func)} | |
2e2b4d24 | 94 | Begin editing a label. This can be prevented by calling Veto(). |
232fdc63 | 95 | Processes a @c wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT event type. |
2e2b4d24 RR |
96 | @event{EVT_LIST_END_LABEL_EDIT(id, func)} |
97 | Finish editing a label. This can be prevented by calling Veto(). | |
232fdc63 | 98 | Processes a @c wxEVT_COMMAND_LIST_END_LABEL_EDIT event type. |
2e2b4d24 RR |
99 | @event{EVT_LIST_DELETE_ITEM(id, func)} |
100 | An item was deleted. | |
232fdc63 | 101 | Processes a @c wxEVT_COMMAND_LIST_DELETE_ITEM event type. |
2e2b4d24 RR |
102 | @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)} |
103 | All items were deleted. | |
232fdc63 | 104 | Processes a @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event type. |
2e2b4d24 RR |
105 | @event{EVT_LIST_ITEM_SELECTED(id, func)} |
106 | The item has been selected. | |
232fdc63 | 107 | Processes a @c wxEVT_COMMAND_LIST_ITEM_SELECTED event type. |
2e2b4d24 RR |
108 | @event{EVT_LIST_ITEM_DESELECTED(id, func)} |
109 | The item has been deselected. | |
232fdc63 | 110 | Processes a @c wxEVT_COMMAND_LIST_ITEM_DESELECTED event type. |
2e2b4d24 RR |
111 | @event{EVT_LIST_ITEM_ACTIVATED(id, func)} |
112 | The item has been activated (ENTER or double click). | |
232fdc63 | 113 | Processes a @c wxEVT_COMMAND_LIST_ITEM_ACTIVATED event type. |
2e2b4d24 RR |
114 | @event{EVT_LIST_ITEM_FOCUSED(id, func)} |
115 | The currently focused item has changed. | |
232fdc63 | 116 | Processes a @c wxEVT_COMMAND_LIST_ITEM_FOCUSED event type. |
2e2b4d24 | 117 | @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)} |
232fdc63 VZ |
118 | The middle mouse button has been clicked on an item. This is |
119 | only supported by the generic control. | |
120 | Processes a @c wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK event type. | |
2e2b4d24 | 121 | @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)} |
320ab87c | 122 | The right mouse button has been clicked on an item. |
232fdc63 | 123 | Processes a @c wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK event type. |
2e2b4d24 RR |
124 | @event{EVT_LIST_KEY_DOWN(id, func)} |
125 | A key has been pressed. | |
232fdc63 | 126 | Processes a @c wxEVT_COMMAND_LIST_KEY_DOWN event type. |
2e2b4d24 RR |
127 | @event{EVT_LIST_INSERT_ITEM(id, func)} |
128 | An item has been inserted. | |
232fdc63 | 129 | Processes a @c wxEVT_COMMAND_LIST_INSERT_ITEM event type. |
2e2b4d24 RR |
130 | @event{EVT_LIST_COL_CLICK(id, func)} |
131 | A column (m_col) has been left-clicked. | |
232fdc63 | 132 | Processes a @c wxEVT_COMMAND_LIST_COL_CLICK event type. |
2e2b4d24 RR |
133 | @event{EVT_LIST_COL_RIGHT_CLICK(id, func)} |
134 | A column (m_col) has been right-clicked. | |
232fdc63 | 135 | Processes a @c wxEVT_COMMAND_LIST_COL_RIGHT_CLICK event type. |
2e2b4d24 RR |
136 | @event{EVT_LIST_COL_BEGIN_DRAG(id, func)} |
137 | The user started resizing a column - can be vetoed. | |
232fdc63 | 138 | Processes a @c wxEVT_COMMAND_LIST_COL_BEGIN_DRAG event type. |
2e2b4d24 RR |
139 | @event{EVT_LIST_COL_DRAGGING(id, func)} |
140 | The divider between columns is being dragged. | |
232fdc63 | 141 | Processes a @c wxEVT_COMMAND_LIST_COL_DRAGGING event type. |
2e2b4d24 RR |
142 | @event{EVT_LIST_COL_END_DRAG(id, func)} |
143 | A column has been resized by the user. | |
232fdc63 | 144 | Processes a @c wxEVT_COMMAND_LIST_COL_END_DRAG event type. |
2e2b4d24 RR |
145 | @event{EVT_LIST_CACHE_HINT(id, func)} |
146 | Prepare cache for a virtual list control. | |
232fdc63 | 147 | Processes a @c wxEVT_COMMAND_LIST_CACHE_HINT event type. |
2e2b4d24 RR |
148 | @endEventTable |
149 | ||
150 | ||
23324ae1 FM |
151 | @library{wxcore} |
152 | @category{ctrl} | |
7e59b885 | 153 | @appearance{listctrl.png} |
7c913512 | 154 | |
320ab87c FM |
155 | @see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList, |
156 | wxListEvent, wxListItem, wxEditableListBox | |
23324ae1 FM |
157 | */ |
158 | class wxListCtrl : public wxControl | |
159 | { | |
160 | public: | |
b45506e8 | 161 | /** |
1d7c0c08 | 162 | Default constructor. |
b45506e8 VZ |
163 | */ |
164 | wxListCtrl(); | |
165 | ||
23324ae1 FM |
166 | /** |
167 | Constructor, creating and showing a list control. | |
3c4f71cc | 168 | |
7c913512 | 169 | @param parent |
4cc4bfaf | 170 | Parent window. Must not be @NULL. |
7c913512 | 171 | @param id |
4cc4bfaf | 172 | Window identifier. The value wxID_ANY indicates a default value. |
7c913512 | 173 | @param pos |
4cc4bfaf | 174 | Window position. |
dc1b07fd | 175 | If ::wxDefaultPosition is specified then a default position is chosen. |
7c913512 | 176 | @param size |
320ab87c | 177 | Window size. |
dc1b07fd | 178 | If ::wxDefaultSize is specified then the window is sized appropriately. |
7c913512 | 179 | @param style |
4cc4bfaf | 180 | Window style. See wxListCtrl. |
7c913512 | 181 | @param validator |
4cc4bfaf | 182 | Window validator. |
7c913512 | 183 | @param name |
4cc4bfaf | 184 | Window name. |
3c4f71cc | 185 | |
4cc4bfaf | 186 | @see Create(), wxValidator |
23324ae1 | 187 | */ |
7c913512 FM |
188 | wxListCtrl(wxWindow* parent, wxWindowID id, |
189 | const wxPoint& pos = wxDefaultPosition, | |
190 | const wxSize& size = wxDefaultSize, | |
191 | long style = wxLC_ICON, | |
192 | const wxValidator& validator = wxDefaultValidator, | |
193 | const wxString& name = wxListCtrlNameStr); | |
23324ae1 FM |
194 | |
195 | /** | |
196 | Destructor, destroying the list control. | |
197 | */ | |
adaaa686 | 198 | virtual ~wxListCtrl(); |
23324ae1 | 199 | |
c23edb1b VZ |
200 | /** |
201 | Adds a new column to the list control in report view mode. | |
202 | ||
203 | This is just a convenient wrapper for InsertColumn() which adds the new | |
204 | column after all the existing ones without having to specify its | |
205 | position explicitly. | |
206 | ||
207 | @since 2.9.4 | |
208 | */ | |
209 | long AppendColumn(const wxString& heading, | |
210 | int format = wxLIST_FORMAT_LEFT, | |
211 | int width = -1); | |
212 | ||
23324ae1 | 213 | /** |
320ab87c FM |
214 | Arranges the items in icon or small icon view. |
215 | This only has effect on Win32. @a flag is one of: | |
1d7c0c08 RR |
216 | - wxLIST_ALIGN_DEFAULT: Default alignment. |
217 | - wxLIST_ALIGN_LEFT: Align to the left side of the control. | |
218 | - wxLIST_ALIGN_TOP: Align to the top side of the control. | |
219 | - wxLIST_ALIGN_SNAP_TO_GRID: Snap to grid. | |
23324ae1 FM |
220 | */ |
221 | bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); | |
222 | ||
223 | /** | |
320ab87c FM |
224 | Sets the image list associated with the control and takes ownership of it |
225 | (i.e. the control will, unlike when using SetImageList(), delete the list | |
226 | when destroyed). @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL, | |
227 | @c wxIMAGE_LIST_STATE (the last is unimplemented). | |
3c4f71cc | 228 | |
4cc4bfaf | 229 | @see SetImageList() |
23324ae1 FM |
230 | */ |
231 | void AssignImageList(wxImageList* imageList, int which); | |
232 | ||
233 | /** | |
234 | Deletes all items and all columns. | |
232fdc63 VZ |
235 | |
236 | @note This sends an event of type @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS | |
237 | under all platforms. | |
23324ae1 FM |
238 | */ |
239 | void ClearAll(); | |
240 | ||
241 | /** | |
242 | Creates the list control. See wxListCtrl() for further details. | |
243 | */ | |
244 | bool Create(wxWindow* parent, wxWindowID id, | |
245 | const wxPoint& pos = wxDefaultPosition, | |
246 | const wxSize& size = wxDefaultSize, | |
247 | long style = wxLC_ICON, | |
248 | const wxValidator& validator = wxDefaultValidator, | |
249 | const wxString& name = wxListCtrlNameStr); | |
250 | ||
251 | /** | |
252 | Deletes all items in the list control. | |
320ab87c | 253 | |
4b97af90 VZ |
254 | This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM |
255 | event because deleting many items from the control would be too slow | |
256 | then (unlike wxListCtrl::DeleteItem) but it does send the special @c | |
257 | wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event if the control was not empty. | |
258 | If it was already empty, nothing is done and no event is sent. | |
259 | ||
260 | @return @true if the items were successfully deleted or if the control | |
261 | was already empty, @false if an error occurred while deleting the | |
262 | items. | |
23324ae1 FM |
263 | */ |
264 | bool DeleteAllItems(); | |
265 | ||
266 | /** | |
267 | Deletes a column. | |
268 | */ | |
269 | bool DeleteColumn(int col); | |
270 | ||
271 | /** | |
320ab87c FM |
272 | Deletes the specified item. |
273 | This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the | |
274 | item being deleted. | |
275 | ||
276 | @see DeleteAllItems() | |
23324ae1 FM |
277 | */ |
278 | bool DeleteItem(long item); | |
279 | ||
280 | /** | |
320ab87c FM |
281 | Starts editing the label of the given item. |
282 | ||
283 | This function generates a @c EVT_LIST_BEGIN_LABEL_EDIT event which can be | |
284 | vetoed so that no text control will appear for in-place editing. | |
285 | ||
23324ae1 | 286 | If the user changed the label (i.e. s/he does not press ESC or leave |
320ab87c | 287 | the text control without changes, a @c EVT_LIST_END_LABEL_EDIT event |
23324ae1 FM |
288 | will be sent which can be vetoed as well. |
289 | */ | |
5267aefd | 290 | wxTextCtrl* EditLabel(long item, |
b19b28c8 | 291 | wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl)); |
23324ae1 | 292 | |
747eb0f6 VZ |
293 | /** |
294 | Finish editing the label. | |
295 | ||
296 | This method allows to programmatically end editing a list control item | |
297 | in place. Usually it will only be called when editing is in progress, | |
417b8fcc VZ |
298 | i.e. if GetEditControl() returns non-NULL. In particular, do not call |
299 | it from EVT_LIST_BEGIN_LABEL_EDIT handler as the edit control is not | |
300 | yet fully created by then, just veto the event in this handler instead | |
301 | to prevent the editing from even starting. | |
302 | ||
303 | Notice that calling this method will result in EVT_LIST_END_LABEL_EDIT | |
304 | event being generated. | |
747eb0f6 VZ |
305 | |
306 | Currently only implemented in wxMSW. | |
307 | ||
308 | @param cancel If @true, discard the changes made by user, as if @c | |
309 | Escape key was pressed. Otherwise, accept the changes as if @c | |
310 | Return was pressed. | |
311 | @return @true if item editing wad finished or @false if no item as | |
312 | being edited. | |
313 | */ | |
314 | bool EndEditLabel(bool cancel); | |
315 | ||
23324ae1 FM |
316 | /** |
317 | Ensures this item is visible. | |
318 | */ | |
319 | bool EnsureVisible(long item); | |
320 | ||
23324ae1 | 321 | /** |
320ab87c FM |
322 | Find an item whose label matches this string, starting from start or the |
323 | beginning if start is @c -1. The string comparison is case insensitive. | |
324 | ||
325 | If @a partial is @true then this method will look for items which begin with @a str. | |
c2ebca9b VZ |
326 | |
327 | @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise. | |
23324ae1 FM |
328 | */ |
329 | long FindItem(long start, const wxString& str, | |
4cc4bfaf | 330 | bool partial = false); |
320ab87c | 331 | |
1d7c0c08 | 332 | /** |
320ab87c FM |
333 | Find an item whose data matches this data, starting from start or the |
334 | beginning if 'start' is @c -1. | |
1058f652 MB |
335 | |
336 | @beginWxPerlOnly | |
337 | In wxPerl this method is implemented as FindItemData(start, data). | |
338 | @endWxPerlOnly | |
c2ebca9b VZ |
339 | |
340 | @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise. | |
1d7c0c08 | 341 | */ |
0a98423e | 342 | long FindItem(long start, wxUIntPtr data); |
320ab87c | 343 | |
1d7c0c08 RR |
344 | /** |
345 | Find an item nearest this position in the specified direction, | |
346 | starting from @a start or the beginning if @a start is -1. | |
1058f652 MB |
347 | |
348 | @beginWxPerlOnly | |
349 | In wxPerl this method is implemented as FindItemAtPos(start, pt, direction). | |
350 | @endWxPerlOnly | |
c2ebca9b VZ |
351 | |
352 | @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise. | |
1d7c0c08 | 353 | */ |
7c913512 | 354 | long FindItem(long start, const wxPoint& pt, int direction); |
23324ae1 FM |
355 | |
356 | /** | |
320ab87c FM |
357 | Gets information about this column. |
358 | See SetItem() for more information. | |
1058f652 MB |
359 | |
360 | @beginWxPerlOnly | |
361 | In wxPerl this method takes only the @a col parameter and | |
362 | returns a @c Wx::ListItem (or @c undef). | |
363 | @endWxPerlOnly | |
23324ae1 | 364 | */ |
328f5751 | 365 | bool GetColumn(int col, wxListItem& item) const; |
23324ae1 FM |
366 | |
367 | /** | |
368 | Returns the number of columns. | |
369 | */ | |
328f5751 | 370 | int GetColumnCount() const; |
23324ae1 FM |
371 | |
372 | /** | |
80cc5fc7 VZ |
373 | Gets the column index from its position in visual order. |
374 | ||
375 | After calling SetColumnsOrder(), the index returned by this function | |
376 | corresponds to the value of the element number @a pos in the array | |
377 | returned by GetColumnsOrder(). | |
378 | ||
379 | Please see SetColumnsOrder() documentation for an example and | |
380 | additional remarks about the columns ordering. | |
381 | ||
382 | @see GetColumnOrder() | |
23324ae1 | 383 | */ |
80cc5fc7 | 384 | int GetColumnIndexFromOrder(int pos) const; |
23324ae1 FM |
385 | |
386 | /** | |
80cc5fc7 VZ |
387 | Gets the column visual order position. |
388 | ||
389 | This function returns the index of the column which appears at the | |
390 | given visual position, e.g. calling it with @a col equal to 0 returns | |
391 | the index of the first shown column. | |
392 | ||
393 | Please see SetColumnsOrder() documentation for an example and | |
394 | additional remarks about the columns ordering. | |
395 | ||
396 | @see GetColumnsOrder(), GetColumnIndexFromOrder() | |
23324ae1 | 397 | */ |
328f5751 | 398 | int GetColumnOrder(int col) const; |
23324ae1 FM |
399 | |
400 | /** | |
401 | Gets the column width (report view only). | |
402 | */ | |
328f5751 | 403 | int GetColumnWidth(int col) const; |
23324ae1 FM |
404 | |
405 | /** | |
320ab87c | 406 | Returns the array containing the orders of all columns. |
80cc5fc7 | 407 | |
320ab87c | 408 | On error, an empty array is returned. |
80cc5fc7 VZ |
409 | |
410 | Please see SetColumnsOrder() documentation for an example and | |
411 | additional remarks about the columns ordering. | |
412 | ||
413 | @see GetColumnOrder(), GetColumnIndexFromOrder() | |
23324ae1 | 414 | */ |
328f5751 | 415 | wxArrayInt GetColumnsOrder() const; |
23324ae1 FM |
416 | |
417 | /** | |
320ab87c FM |
418 | Gets the number of items that can fit vertically in the visible area of |
419 | the list control (list or report view) or the total number of items in | |
420 | the list control (icon or small icon view). | |
23324ae1 | 421 | */ |
328f5751 | 422 | int GetCountPerPage() const; |
23324ae1 FM |
423 | |
424 | /** | |
320ab87c FM |
425 | Returns the edit control being currently used to edit a label. |
426 | Returns @NULL if no label is being edited. | |
427 | ||
1f1d2182 | 428 | @note It is currently only implemented for wxMSW and the generic version, |
320ab87c | 429 | not for the native Mac OS X version. |
23324ae1 | 430 | */ |
328f5751 | 431 | wxTextCtrl* GetEditControl() const; |
23324ae1 FM |
432 | |
433 | /** | |
4cc4bfaf | 434 | Returns the specified image list. @a which may be one of: |
1d7c0c08 RR |
435 | - wxIMAGE_LIST_NORMAL: The normal (large icon) image list. |
436 | - wxIMAGE_LIST_SMALL: The small icon image list. | |
437 | - wxIMAGE_LIST_STATE: The user-defined state image list (unimplemented). | |
23324ae1 | 438 | */ |
328f5751 | 439 | wxImageList* GetImageList(int which) const; |
23324ae1 FM |
440 | |
441 | /** | |
320ab87c | 442 | Gets information about the item. See SetItem() for more information. |
c86b476d FM |
443 | |
444 | You must call @e info.SetId() to set the ID of item you're interested in | |
445 | before calling this method, and @e info.SetMask() with the flags indicating | |
446 | what fields you need to retrieve from @a info. | |
1058f652 MB |
447 | |
448 | @beginWxPerlOnly | |
449 | In wxPerl this method takes as parameter the ID of the item | |
450 | and (optionally) the column, and returns a Wx::ListItem object. | |
451 | @endWxPerlOnly | |
23324ae1 | 452 | */ |
328f5751 | 453 | bool GetItem(wxListItem& info) const; |
23324ae1 FM |
454 | |
455 | /** | |
320ab87c FM |
456 | Returns the colour for this item. |
457 | If the item has no specific colour, returns an invalid colour | |
458 | (and not the default background control of the control itself). | |
3c4f71cc | 459 | |
4cc4bfaf | 460 | @see GetItemTextColour() |
23324ae1 | 461 | */ |
328f5751 | 462 | wxColour GetItemBackgroundColour(long item) const; |
23324ae1 FM |
463 | |
464 | /** | |
465 | Returns the number of items in the list control. | |
466 | */ | |
328f5751 | 467 | int GetItemCount() const; |
23324ae1 FM |
468 | |
469 | /** | |
470 | Gets the application-defined data associated with this item. | |
471 | */ | |
5267aefd | 472 | wxUIntPtr GetItemData(long item) const; |
23324ae1 FM |
473 | |
474 | /** | |
475 | Returns the item's font. | |
476 | */ | |
328f5751 | 477 | wxFont GetItemFont(long item) const; |
23324ae1 FM |
478 | |
479 | /** | |
480 | Returns the position of the item, in icon or small icon view. | |
1058f652 MB |
481 | |
482 | @beginWxPerlOnly | |
483 | In wxPerl this method takes only the @a item parameter and | |
484 | returns a @c Wx::Point (or @c undef). | |
485 | @endWxPerlOnly | |
23324ae1 | 486 | */ |
328f5751 | 487 | bool GetItemPosition(long item, wxPoint& pos) const; |
23324ae1 FM |
488 | |
489 | /** | |
490 | Returns the rectangle representing the item's size and position, in physical | |
491 | coordinates. | |
320ab87c | 492 | |
4cc4bfaf | 493 | @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL. |
1058f652 MB |
494 | |
495 | @beginWxPerlOnly | |
496 | In wxPerl this method takes only the @a item and @a code parameters and | |
497 | returns a @c Wx::Rect (or @c undef). | |
498 | @endWxPerlOnly | |
23324ae1 FM |
499 | */ |
500 | bool GetItemRect(long item, wxRect& rect, | |
328f5751 | 501 | int code = wxLIST_RECT_BOUNDS) const; |
23324ae1 FM |
502 | |
503 | /** | |
320ab87c FM |
504 | Retrieves the spacing between icons in pixels: horizontal spacing is |
505 | returned as @c x component of the wxSize object and the vertical spacing | |
506 | as its @c y component. | |
23324ae1 | 507 | */ |
328f5751 | 508 | wxSize GetItemSpacing() const; |
23324ae1 FM |
509 | |
510 | /** | |
511 | Gets the item state. For a list of state flags, see SetItem(). | |
320ab87c | 512 | The @a stateMask indicates which state flags are of interest. |
23324ae1 | 513 | */ |
328f5751 | 514 | int GetItemState(long item, long stateMask) const; |
23324ae1 FM |
515 | |
516 | /** | |
517 | Gets the item text for this item. | |
b6812a6f VZ |
518 | |
519 | @param item | |
520 | Item (zero-based) index. | |
521 | @param col | |
522 | Item column (zero-based) index. Column 0 is the default. This | |
523 | parameter is new in wxWidgets 2.9.1. | |
23324ae1 | 524 | */ |
b6812a6f | 525 | wxString GetItemText(long item, int col = 0) const; |
23324ae1 FM |
526 | |
527 | /** | |
320ab87c FM |
528 | Returns the colour for this item. |
529 | ||
530 | If the item has no specific colour, returns an invalid colour (and not the | |
531 | default foreground control of the control itself as this wouldn't allow | |
532 | distinguishing between items having the same colour as the current control | |
533 | foreground and items with default colour which, hence, have always the | |
534 | same colour as the control). | |
23324ae1 | 535 | */ |
328f5751 | 536 | wxColour GetItemTextColour(long item) const; |
23324ae1 FM |
537 | |
538 | /** | |
539 | Searches for an item with the given geometry or state, starting from | |
320ab87c | 540 | @a item but excluding the @a item itself. |
3c4f71cc | 541 | |
320ab87c FM |
542 | If @a item is -1, the first item that matches the specified flags will be returned. |
543 | Returns the first item with given state following @a item or -1 if no such item found. | |
544 | This function may be used to find all selected items in the control like this: | |
3c4f71cc | 545 | |
320ab87c FM |
546 | @code |
547 | long item = -1; | |
548 | for ( ;; ) | |
549 | { | |
550 | item = listctrl->GetNextItem(item, | |
551 | wxLIST_NEXT_ALL, | |
552 | wxLIST_STATE_SELECTED); | |
553 | if ( item == -1 ) | |
554 | break; | |
555 | ||
556 | // this item is selected - do whatever is needed with it | |
557 | wxLogMessage("Item %ld is selected.", item); | |
558 | } | |
559 | @endcode | |
3c4f71cc | 560 | |
320ab87c FM |
561 | @a geometry can be one of: |
562 | - wxLIST_NEXT_ABOVE: Searches for an item above the specified item. | |
563 | - wxLIST_NEXT_ALL: Searches for subsequent item by index. | |
564 | - wxLIST_NEXT_BELOW: Searches for an item below the specified item. | |
565 | - wxLIST_NEXT_LEFT: Searches for an item to the left of the specified item. | |
566 | - wxLIST_NEXT_RIGHT: Searches for an item to the right of the specified item. | |
3c4f71cc | 567 | |
1f1d2182 | 568 | @note this parameter is only supported by wxMSW currently and ignored on |
320ab87c | 569 | other platforms. |
3c4f71cc | 570 | |
320ab87c FM |
571 | @a state can be a bitlist of the following: |
572 | - wxLIST_STATE_DONTCARE: Don't care what the state is. | |
573 | - wxLIST_STATE_DROPHILITED: The item indicates it is a drop target. | |
574 | - wxLIST_STATE_FOCUSED: The item has the focus. | |
575 | - wxLIST_STATE_SELECTED: The item is selected. | |
576 | - wxLIST_STATE_CUT: The item is selected as part of a cut and paste operation. | |
23324ae1 FM |
577 | */ |
578 | long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, | |
328f5751 | 579 | int state = wxLIST_STATE_DONTCARE) const; |
23324ae1 FM |
580 | |
581 | /** | |
582 | Returns the number of selected items in the list control. | |
583 | */ | |
328f5751 | 584 | int GetSelectedItemCount() const; |
23324ae1 FM |
585 | |
586 | /** | |
587 | Returns the rectangle representing the size and position, in physical | |
4cc4bfaf | 588 | coordinates, of the given subitem, i.e. the part of the row @a item in the |
320ab87c FM |
589 | column @a subItem. |
590 | ||
d13b34d3 | 591 | This method is only meaningful when the wxListCtrl is in the report mode. |
320ab87c | 592 | If @a subItem parameter is equal to the special value |
23324ae1 FM |
593 | @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as |
594 | for GetItemRect(). | |
320ab87c FM |
595 | |
596 | @a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or | |
597 | @c wxLIST_RECT_LABEL. | |
3c4f71cc | 598 | |
1e24c2af | 599 | @since 2.7.0 |
23324ae1 FM |
600 | */ |
601 | bool GetSubItemRect(long item, long subItem, wxRect& rect, | |
328f5751 | 602 | int code = wxLIST_RECT_BOUNDS) const; |
23324ae1 FM |
603 | |
604 | /** | |
605 | Gets the text colour of the list control. | |
606 | */ | |
328f5751 | 607 | wxColour GetTextColour() const; |
23324ae1 FM |
608 | |
609 | /** | |
320ab87c | 610 | Gets the index of the topmost visible item when in list or report view. |
23324ae1 | 611 | */ |
328f5751 | 612 | long GetTopItem() const; |
23324ae1 FM |
613 | |
614 | /** | |
615 | Returns the rectangle taken by all items in the control. In other words, if the | |
616 | controls client size were equal to the size of this rectangle, no scrollbars | |
617 | would be needed and no free space would be left. | |
320ab87c | 618 | |
23324ae1 FM |
619 | Note that this function only works in the icon and small icon views, not in |
620 | list or report views (this is a limitation of the native Win32 control). | |
621 | */ | |
328f5751 | 622 | wxRect GetViewRect() const; |
23324ae1 FM |
623 | |
624 | /** | |
320ab87c FM |
625 | Determines which item (if any) is at the specified point, giving details |
626 | in @a flags. Returns index of the item or @c wxNOT_FOUND if no item is at | |
627 | the specified point. | |
3c4f71cc | 628 | |
320ab87c FM |
629 | @a flags will be a combination of the following flags: |
630 | - wxLIST_HITTEST_ABOVE: Above the client area. | |
631 | - wxLIST_HITTEST_BELOW: Below the client area. | |
632 | - wxLIST_HITTEST_NOWHERE: In the client area but below the last item. | |
633 | - wxLIST_HITTEST_ONITEMICON: On the bitmap associated with an item. | |
634 | - wxLIST_HITTEST_ONITEMLABEL: On the label (string) associated with an item. | |
635 | - wxLIST_HITTEST_ONITEMRIGHT: In the area to the right of an item. | |
636 | - wxLIST_HITTEST_ONITEMSTATEICON: On the state icon for a tree view item | |
637 | that is in a user-defined state. | |
638 | - wxLIST_HITTEST_TOLEFT: To the right of the client area. | |
639 | - wxLIST_HITTEST_TORIGHT: To the left of the client area. | |
640 | - wxLIST_HITTEST_ONITEM: Combination of @c wxLIST_HITTEST_ONITEMICON, | |
641 | @c wxLIST_HITTEST_ONITEMLABEL, @c wxLIST_HITTEST_ONITEMSTATEICON. | |
3c4f71cc | 642 | |
4cc4bfaf | 643 | If @a ptrSubItem is not @NULL and the wxListCtrl is in the report |
7c913512 | 644 | mode the subitem (or column) number will also be provided. |
23324ae1 FM |
645 | This feature is only available in version 2.7.0 or higher and is currently only |
646 | implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on | |
320ab87c FM |
647 | the host system or the value stored in @a ptrSubItem will be always -1. |
648 | To compile this feature into wxWidgets library you need to have access to | |
23324ae1 | 649 | commctrl.h of version 4.70 that is provided by Microsoft. |
1058f652 MB |
650 | |
651 | @beginWxPerlOnly | |
652 | In wxPerl this method only takes the @a point parameter | |
653 | and returns a 2-element list (item, flags). | |
654 | @endWxPerlOnly | |
23324ae1 | 655 | */ |
5267aefd | 656 | long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const; |
23324ae1 | 657 | |
54d323d2 VZ |
658 | /** |
659 | Returns true if the control is currently using ::wxLC_REPORT style. | |
660 | */ | |
661 | bool InReportView() const; | |
662 | ||
23324ae1 | 663 | /** |
0fb731b8 VZ |
664 | For report view mode (only), inserts a column. |
665 | ||
666 | For more details, see SetItem(). Also see InsertColumn(long, const | |
667 | wxString&, int, int) overload for a usually more convenient | |
668 | alternative to this method and the description of how the item width | |
669 | is interpreted by this method. | |
23324ae1 | 670 | */ |
0fb731b8 | 671 | long InsertColumn(long col, const wxListItem& info); |
320ab87c | 672 | |
1d7c0c08 | 673 | /** |
0fb731b8 VZ |
674 | For report view mode (only), inserts a column. |
675 | ||
676 | Insert a new column in the list control in report view mode at the | |
677 | given position specifying its most common attributes. | |
678 | ||
679 | Notice that to set the image for the column you need to use | |
680 | Insert(long, const wxListItem&) overload and specify ::wxLIST_MASK_IMAGE | |
681 | in the item mask. | |
682 | ||
683 | @param col | |
684 | The index where the column should be inserted. Valid indices are | |
685 | from 0 up to GetColumnCount() inclusive and the latter can be used | |
686 | to append the new column after the last existing one. | |
687 | @param heading | |
688 | The string specifying the column heading. | |
689 | @param format | |
690 | The flags specifying the control heading text alignment. | |
691 | @param width | |
692 | If positive, the width of the column in pixels. Otherwise it can be | |
693 | @c wxLIST_AUTOSIZE to choose the default size for the column or @c | |
694 | wxLIST_AUTOSIZE_USEHEADER to fit the column width to @a heading or | |
695 | to extend to fill all the remaining space for the last column. | |
696 | Notice that in case of @c wxLIST_AUTOSIZE fixed width is used as | |
697 | there are no items in this column to use for determining its best | |
698 | size yet. If you want to fit the column to its contents, use | |
699 | SetColumnWidth() after adding the items with values in this column. | |
700 | @return | |
701 | The index of the inserted column or -1 if adding it failed. | |
1d7c0c08 | 702 | */ |
7c913512 FM |
703 | long InsertColumn(long col, const wxString& heading, |
704 | int format = wxLIST_FORMAT_LEFT, | |
0fb731b8 | 705 | int width = wxLIST_AUTOSIZE); |
23324ae1 | 706 | |
23324ae1 | 707 | /** |
320ab87c FM |
708 | Inserts an item, returning the index of the new item if successful, -1 otherwise. |
709 | ||
7c913512 | 710 | @param info |
4cc4bfaf | 711 | wxListItem object |
b45506e8 VZ |
712 | */ |
713 | long InsertItem(wxListItem& info); | |
714 | ||
715 | /** | |
716 | Insert an string item. | |
320ab87c | 717 | |
7c913512 | 718 | @param index |
4cc4bfaf | 719 | Index of the new item, supplied by the application |
7c913512 | 720 | @param label |
4cc4bfaf | 721 | String label |
1058f652 MB |
722 | |
723 | @beginWxPerlOnly | |
724 | In wxPerl this method is implemented as InsertStringItem(index, label). | |
725 | @endWxPerlOnly | |
23324ae1 | 726 | */ |
7c913512 | 727 | long InsertItem(long index, const wxString& label); |
320ab87c | 728 | |
b45506e8 VZ |
729 | /** |
730 | Insert an image item. | |
320ab87c | 731 | |
b45506e8 VZ |
732 | @param index |
733 | Index of the new item, supplied by the application | |
734 | @param imageIndex | |
735 | Index into the image list associated with this control and view style | |
1058f652 MB |
736 | |
737 | @beginWxPerlOnly | |
738 | In wxPerl this method is implemented as InsertImageItem(index, imageIndex). | |
739 | @endWxPerlOnly | |
320ab87c | 740 | */ |
7c913512 | 741 | long InsertItem(long index, int imageIndex); |
320ab87c | 742 | |
b45506e8 VZ |
743 | /** |
744 | Insert an image/string item. | |
320ab87c | 745 | |
b45506e8 VZ |
746 | @param index |
747 | Index of the new item, supplied by the application | |
748 | @param label | |
749 | String label | |
750 | @param imageIndex | |
751 | Index into the image list associated with this control and view style | |
1058f652 MB |
752 | |
753 | @beginWxPerlOnly | |
754 | In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex). | |
755 | @endWxPerlOnly | |
320ab87c | 756 | */ |
7c913512 FM |
757 | long InsertItem(long index, const wxString& label, |
758 | int imageIndex); | |
23324ae1 | 759 | |
54d323d2 VZ |
760 | /** |
761 | Returns true if the control is currently in virtual report view. | |
762 | */ | |
763 | bool IsVirtual() const; | |
764 | ||
23324ae1 | 765 | /** |
320ab87c FM |
766 | Redraws the given @e item. |
767 | ||
768 | This is only useful for the virtual list controls as without calling this | |
769 | function the displayed value of the item doesn't change even when the | |
770 | underlying data does change. | |
3c4f71cc | 771 | |
4cc4bfaf | 772 | @see RefreshItems() |
23324ae1 FM |
773 | */ |
774 | void RefreshItem(long item); | |
775 | ||
776 | /** | |
320ab87c FM |
777 | Redraws the items between @a itemFrom and @e itemTo. |
778 | The starting item must be less than or equal to the ending one. | |
779 | ||
780 | Just as RefreshItem() this is only useful for virtual list controls. | |
23324ae1 FM |
781 | */ |
782 | void RefreshItems(long itemFrom, long itemTo); | |
783 | ||
784 | /** | |
785 | Scrolls the list control. If in icon, small icon or report view mode, | |
4cc4bfaf FM |
786 | @a dx specifies the number of pixels to scroll. If in list view mode, |
787 | @a dx specifies the number of columns to scroll. @a dy always specifies | |
23324ae1 | 788 | the number of pixels to scroll vertically. |
320ab87c | 789 | |
1f1d2182 | 790 | @note This method is currently only implemented in the Windows version. |
23324ae1 FM |
791 | */ |
792 | bool ScrollList(int dx, int dy); | |
793 | ||
794 | /** | |
320ab87c FM |
795 | Sets the background colour. |
796 | ||
797 | Note that the wxWindow::GetBackgroundColour() function of wxWindow base | |
798 | class can be used to retrieve the current background colour. | |
23324ae1 | 799 | */ |
5267aefd | 800 | virtual bool SetBackgroundColour(const wxColour& col); |
23324ae1 FM |
801 | |
802 | /** | |
320ab87c FM |
803 | Sets information about this column. |
804 | See SetItem() for more information. | |
23324ae1 FM |
805 | */ |
806 | bool SetColumn(int col, wxListItem& item); | |
807 | ||
808 | /** | |
809 | Sets the column width. | |
320ab87c FM |
810 | |
811 | @a width can be a width in pixels or @c wxLIST_AUTOSIZE (-1) or | |
812 | @c wxLIST_AUTOSIZE_USEHEADER (-2). | |
813 | ||
814 | @c wxLIST_AUTOSIZE will resize the column to the length of its longest item. | |
815 | ||
816 | @c wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the | |
817 | header (Win32) or 80 pixels (other platforms). | |
818 | ||
4cc4bfaf | 819 | In small or normal icon view, @a col must be -1, and the column width is set |
23324ae1 FM |
820 | for all columns. |
821 | */ | |
822 | bool SetColumnWidth(int col, int width); | |
823 | ||
824 | /** | |
80cc5fc7 VZ |
825 | Changes the order in which the columns are shown. |
826 | ||
827 | By default, the columns of a list control appear on the screen in order | |
828 | of their indices, i.e. the column 0 appears first, the column 1 next | |
829 | and so on. However by using this function it is possible to arbitrarily | |
830 | reorder the columns visual order and the user can also rearrange the | |
831 | columns interactively by dragging them. In this case, the index of the | |
832 | column is not the same as its order and the functions GetColumnOrder() | |
833 | and GetColumnIndexFromOrder() should be used to translate between them. | |
834 | Notice that all the other functions still work with the column indices, | |
835 | i.e. the visual positioning of the columns on screen doesn't affect the | |
836 | code setting or getting their values for example. | |
320ab87c FM |
837 | |
838 | The @a orders array must have the same number elements as the number of | |
80cc5fc7 VZ |
839 | columns and contain each position exactly once. Its n-th element |
840 | contains the index of the column to be shown in n-th position, so for a | |
841 | control with three columns passing an array with elements 2, 0 and 1 | |
842 | results in the third column being displayed first, the first one next | |
843 | and the second one last. | |
844 | ||
845 | Example of using it: | |
846 | @code | |
847 | wxListCtrl *list = new wxListCtrl(...); | |
848 | for ( int i = 0; i < 3; i++ ) | |
849 | list->InsertColumn(i, wxString::Format("Column %d", i)); | |
850 | ||
851 | wxArrayInt order(3); | |
852 | order[0] = 2; | |
853 | order[1] = 0; | |
854 | order[2] = 1; | |
855 | list->SetColumnsOrder(order); | |
856 | ||
857 | // now list->GetColumnsOrder() will return order and | |
858 | // list->GetColumnIndexFromOrder(n) will return order[n] and | |
859 | // list->GetColumnOrder() will return 1, 2 and 0 for the column 0, | |
860 | // 1 and 2 respectively | |
861 | @endcode | |
862 | ||
863 | Please notice that this function makes sense for report view only and | |
864 | currently is only implemented in wxMSW port. To avoid explicit tests | |
865 | for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER | |
866 | as this will allow it to start working under the other platforms when | |
867 | support for the column reordering is added there. | |
320ab87c | 868 | |
80cc5fc7 | 869 | @see GetColumnsOrder() |
23324ae1 | 870 | */ |
b5176f6d | 871 | bool SetColumnsOrder(const wxArrayInt& orders); |
23324ae1 FM |
872 | |
873 | /** | |
320ab87c FM |
874 | Sets the image list associated with the control. |
875 | ||
876 | @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL, | |
877 | @c wxIMAGE_LIST_STATE (the last is unimplemented). | |
878 | ||
23324ae1 FM |
879 | This method does not take ownership of the image list, you have to |
880 | delete it yourself. | |
3c4f71cc | 881 | |
4cc4bfaf | 882 | @see AssignImageList() |
23324ae1 FM |
883 | */ |
884 | void SetImageList(wxImageList* imageList, int which); | |
885 | ||
23324ae1 | 886 | /** |
1d7c0c08 | 887 | Sets the data of an item. |
320ab87c FM |
888 | |
889 | Using the wxListItem's mask and state mask, you can change only selected | |
890 | attributes of a wxListCtrl item. | |
23324ae1 FM |
891 | */ |
892 | bool SetItem(wxListItem& info); | |
320ab87c | 893 | |
1d7c0c08 | 894 | /** |
320ab87c | 895 | Sets an item string field at a particular column. |
1d7c0c08 | 896 | */ |
320ab87c | 897 | long SetItem(long index, int column, const wxString& label, int imageId = -1); |
23324ae1 FM |
898 | |
899 | /** | |
320ab87c FM |
900 | Sets the background colour for this item. |
901 | This function only works in report view mode. | |
902 | The colour can be retrieved using GetItemBackgroundColour(). | |
23324ae1 FM |
903 | */ |
904 | void SetItemBackgroundColour(long item, const wxColour& col); | |
905 | ||
906 | /** | |
320ab87c FM |
907 | Sets the image associated with the item. |
908 | In report view, you can specify the column. | |
909 | The image is an index into the image list associated with the list control. | |
23324ae1 FM |
910 | */ |
911 | bool SetItemColumnImage(long item, long column, int image); | |
912 | ||
913 | /** | |
558a6e06 VZ |
914 | This method can only be used with virtual list controls. |
915 | ||
916 | It is used to indicate to the control the number of items it contains. | |
917 | After calling it, the main program should be ready to handle calls to | |
918 | various item callbacks (such as wxListCtrl::OnGetItemText) for all | |
919 | items in the range from 0 to @a count. | |
920 | ||
921 | Notice that the control is not necessarily redrawn after this call as | |
922 | it may be undesirable if an item which is not visible on the screen | |
923 | anyhow was added to or removed from a control displaying many items, if | |
924 | you do need to refresh the display you can just call Refresh() manually. | |
23324ae1 FM |
925 | */ |
926 | void SetItemCount(long count); | |
927 | ||
928 | /** | |
320ab87c FM |
929 | Associates application-defined data with this item. |
930 | ||
931 | Notice that this function cannot be used to associate pointers with the control | |
932 | items, use SetItemPtrData() instead. | |
23324ae1 FM |
933 | */ |
934 | bool SetItemData(long item, long data); | |
935 | ||
936 | /** | |
1d7c0c08 | 937 | Sets the item's font. |
23324ae1 FM |
938 | */ |
939 | void SetItemFont(long item, const wxFont& font); | |
940 | ||
23324ae1 | 941 | /** |
320ab87c FM |
942 | Sets the unselected and selected images associated with the item. |
943 | The images are indices into the image list associated with the list control. | |
23324ae1 | 944 | */ |
5267aefd | 945 | bool SetItemImage(long item, int image, int selImage = -1); |
320ab87c | 946 | |
1d7c0c08 | 947 | /** |
320ab87c FM |
948 | Sets the unselected and selected images associated with the item. |
949 | The images are indices into the image list associated with the list control. | |
950 | ||
951 | @deprecated | |
952 | This form is deprecated: @a selImage is not used; use the other | |
953 | SetItemImage() overload. | |
1d7c0c08 | 954 | */ |
5267aefd | 955 | bool SetItemImage(long item, int image, int selImage = -1); |
23324ae1 FM |
956 | |
957 | /** | |
958 | Sets the position of the item, in icon or small icon view. Windows only. | |
959 | */ | |
960 | bool SetItemPosition(long item, const wxPoint& pos); | |
961 | ||
962 | /** | |
320ab87c FM |
963 | Associates application-defined data with this item. |
964 | ||
965 | The @a data parameter may be either an integer or a pointer cast to the | |
966 | @c wxUIntPtr type which is guaranteed to be large enough to be able to | |
967 | contain all integer types and pointers. | |
3c4f71cc | 968 | |
1e24c2af | 969 | @since 2.8.4 |
23324ae1 FM |
970 | */ |
971 | bool SetItemPtrData(long item, wxUIntPtr data); | |
972 | ||
973 | /** | |
974 | Sets the item state. For a list of state flags, see SetItem(). | |
23324ae1 FM |
975 | The @b stateMask indicates which state flags are valid. |
976 | */ | |
977 | bool SetItemState(long item, long state, long stateMask); | |
978 | ||
979 | /** | |
980 | Sets the item text for this item. | |
981 | */ | |
982 | void SetItemText(long item, const wxString& text); | |
983 | ||
984 | /** | |
320ab87c FM |
985 | Sets the colour for this item. |
986 | This function only works in report view. | |
987 | The colour can be retrieved using GetItemTextColour(). | |
23324ae1 FM |
988 | */ |
989 | void SetItemTextColour(long item, const wxColour& col); | |
990 | ||
991 | /** | |
992 | Adds or removes a single window style. | |
993 | */ | |
4cc4bfaf | 994 | void SetSingleStyle(long style, bool add = true); |
23324ae1 FM |
995 | |
996 | /** | |
997 | Sets the text colour of the list control. | |
998 | */ | |
999 | void SetTextColour(const wxColour& col); | |
1000 | ||
1001 | /** | |
1002 | Sets the whole window style, deleting all items. | |
1003 | */ | |
1004 | void SetWindowStyleFlag(long style); | |
1005 | ||
1006 | /** | |
1007 | Call this function to sort the items in the list control. Sorting is done | |
4cc4bfaf | 1008 | using the specified @a fnSortCallBack function. This function must have the |
23324ae1 | 1009 | following prototype: |
320ab87c | 1010 | @code |
d3ca8487 | 1011 | int wxCALLBACK wxListCompareFunction(wxIntPtr item1, wxIntPtr item2, wxIntPtr sortData) |
320ab87c | 1012 | @endcode |
3c4f71cc | 1013 | |
23324ae1 FM |
1014 | It is called each time when the two items must be compared and should return 0 |
1015 | if the items are equal, negative value if the first item is less than the | |
1016 | second one and positive value if the first one is greater than the second one | |
1017 | (the same convention as used by @c qsort(3)). | |
3c4f71cc | 1018 | |
320ab87c FM |
1019 | The parameter @e item1 is the client data associated with the first item (NOT the index). |
1020 | The parameter @e item2 is the client data associated with the second item (NOT the index). | |
1021 | The parameter @e data is the value passed to SortItems() itself. | |
1022 | ||
1023 | Notice that the control may only be sorted on client data associated with | |
1024 | the items, so you must use SetItemData if you want to be able to sort the | |
1025 | items in the control. | |
1026 | ||
1027 | Please see the @ref page_samples_listctrl for an example of using this function. | |
1058f652 MB |
1028 | |
1029 | @beginWxPerlOnly | |
1030 | In wxPerl the comparison function must take just two parameters; | |
1031 | however, you may use a closure to achieve an effect similar to the | |
1032 | SortItems third parameter. | |
1033 | @endWxPerlOnly | |
23324ae1 | 1034 | */ |
b18e2046 | 1035 | bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data); |
5e6e278d FM |
1036 | |
1037 | protected: | |
1038 | ||
1039 | /** | |
75504144 | 1040 | This function may be overridden in the derived class for a control with |
5e6e278d FM |
1041 | @c wxLC_VIRTUAL style. It should return the attribute for the specified |
1042 | @c item or @NULL to use the default appearance parameters. | |
1043 | ||
1044 | wxListCtrl will not delete the pointer or keep a reference of it. | |
1045 | You can return the same wxListItemAttr pointer for every OnGetItemAttr() call. | |
1046 | ||
1047 | The base class version always returns @NULL. | |
1048 | ||
eab1336c VZ |
1049 | @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(), |
1050 | OnGetItemColumnAttr() | |
5e6e278d FM |
1051 | */ |
1052 | virtual wxListItemAttr* OnGetItemAttr(long item) const; | |
1053 | ||
eab1336c VZ |
1054 | /** |
1055 | This function may be overridden in the derived class for a control with | |
1056 | @c wxLC_VIRTUAL style. | |
1057 | ||
1058 | It should return the attribute for the for the specified @a item and @a | |
1059 | column or @NULL to use the default appearance parameters. | |
1060 | ||
1061 | The base class version returns @c OnGetItemAttr(item). | |
1062 | ||
1063 | @note Currently this function is only called under wxMSW, the other | |
1064 | ports only support OnGetItemAttr() | |
1065 | ||
1066 | @see OnGetItemAttr(), OnGetItemText(), | |
1067 | OnGetItemImage(), OnGetItemColumnImage(), | |
1068 | */ | |
1069 | virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const; | |
1070 | ||
5e6e278d | 1071 | /** |
75504144 | 1072 | Override this function in the derived class for a control with |
5e6e278d FM |
1073 | @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image |
1074 | index for the given line and column. | |
1075 | ||
1076 | The base class version always calls OnGetItemImage() for the first column, else | |
1077 | it returns -1. | |
1078 | ||
eab1336c VZ |
1079 | @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(), |
1080 | OnGetItemColumnAttr() | |
5e6e278d FM |
1081 | */ |
1082 | virtual int OnGetItemColumnImage(long item, long column) const; | |
1083 | ||
1084 | /** | |
75504144 | 1085 | This function must be overridden in the derived class for a control with |
e2c4ccaf | 1086 | @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the |
75504144 | 1087 | control doesn't have an image list, it is not necessary to override it). |
5e6e278d FM |
1088 | It should return the index of the items image in the controls image list |
1089 | or -1 for no image. | |
1090 | ||
1091 | In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for | |
1092 | the first column of each line. | |
1093 | ||
1094 | The base class version always returns -1. | |
1095 | ||
1096 | @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr() | |
1097 | */ | |
1098 | virtual int OnGetItemImage(long item) const; | |
1099 | ||
1100 | /** | |
75504144 | 1101 | This function @b must be overridden in the derived class for a control with |
5e6e278d FM |
1102 | @c wxLC_VIRTUAL style. It should return the string containing the text of |
1103 | the given @a column for the specified @c item. | |
1104 | ||
1105 | @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr() | |
1106 | */ | |
1107 | virtual wxString OnGetItemText(long item, long column) const; | |
23324ae1 FM |
1108 | }; |
1109 | ||
1110 | ||
e54c96f1 | 1111 | |
23324ae1 FM |
1112 | /** |
1113 | @class wxListEvent | |
7c913512 | 1114 | |
23324ae1 | 1115 | A list event holds information about events associated with wxListCtrl objects. |
7c913512 | 1116 | |
320ab87c FM |
1117 | @beginEventTable{wxListEvent} |
1118 | @event{EVT_LIST_BEGIN_DRAG(id, func)} | |
1119 | Begin dragging with the left mouse button. | |
1120 | @event{EVT_LIST_BEGIN_RDRAG(id, func)} | |
1121 | Begin dragging with the right mouse button. | |
1122 | @event{EVT_LIST_BEGIN_LABEL_EDIT(id, func)} | |
1123 | Begin editing a label. This can be prevented by calling Veto(). | |
1124 | @event{EVT_LIST_END_LABEL_EDIT(id, func)} | |
1125 | Finish editing a label. This can be prevented by calling Veto(). | |
1126 | @event{EVT_LIST_DELETE_ITEM(id, func)} | |
1127 | Delete an item. | |
1128 | @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)} | |
1129 | Delete all items. | |
1130 | @event{EVT_LIST_ITEM_SELECTED(id, func)} | |
1131 | The item has been selected. | |
1132 | @event{EVT_LIST_ITEM_DESELECTED(id, func)} | |
1133 | The item has been deselected. | |
1134 | @event{EVT_LIST_ITEM_ACTIVATED(id, func)} | |
1135 | The item has been activated (ENTER or double click). | |
1136 | @event{EVT_LIST_ITEM_FOCUSED(id, func)} | |
1137 | The currently focused item has changed. | |
1138 | @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)} | |
1139 | The middle mouse button has been clicked on an item. | |
1140 | @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)} | |
1141 | The right mouse button has been clicked on an item. | |
1142 | @event{EVT_LIST_KEY_DOWN(id, func)} | |
92d9d10f | 1143 | A key has been pressed. GetIndex() may be -1 if no item is selected. |
320ab87c FM |
1144 | @event{EVT_LIST_INSERT_ITEM(id, func)} |
1145 | An item has been inserted. | |
1146 | @event{EVT_LIST_COL_CLICK(id, func)} | |
1147 | A column (m_col) has been left-clicked. | |
1148 | @event{EVT_LIST_COL_RIGHT_CLICK(id, func)} | |
1149 | A column (m_col) (which can be -1 if the click occurred outside any column) | |
1150 | has been right-clicked. | |
1151 | @event{EVT_LIST_COL_BEGIN_DRAG(id, func)} | |
1152 | The user started resizing a column - can be vetoed. | |
1153 | @event{EVT_LIST_COL_DRAGGING(id, func)} | |
1154 | The divider between columns is being dragged. | |
1155 | @event{EVT_LIST_COL_END_DRAG(id, func)} | |
1156 | A column has been resized by the user. | |
1157 | @event{EVT_LIST_CACHE_HINT(id, func)} | |
1158 | Prepare cache for a virtual list control | |
1159 | @endEventTable | |
1160 | ||
1161 | ||
23324ae1 FM |
1162 | @library{wxbase} |
1163 | @category{events} | |
7c913512 | 1164 | |
e54c96f1 | 1165 | @see wxListCtrl |
23324ae1 FM |
1166 | */ |
1167 | class wxListEvent : public wxNotifyEvent | |
1168 | { | |
1169 | public: | |
1170 | /** | |
1171 | Constructor. | |
1172 | */ | |
0a98423e | 1173 | wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
1174 | |
1175 | /** | |
1176 | For @c EVT_LIST_CACHE_HINT event only: return the first item which the | |
1177 | list control advises us to cache. | |
1178 | */ | |
328f5751 | 1179 | long GetCacheFrom() const; |
23324ae1 FM |
1180 | |
1181 | /** | |
1182 | For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive) | |
1183 | which the list control advises us to cache. | |
1184 | */ | |
328f5751 | 1185 | long GetCacheTo() const; |
23324ae1 FM |
1186 | |
1187 | /** | |
320ab87c FM |
1188 | The column position: it is only used with @c COL events. |
1189 | ||
1190 | For the column dragging events, it is the column to the left of the divider | |
1191 | being dragged, for the column click events it may be -1 if the user clicked | |
1192 | in the list control header outside any column. | |
23324ae1 | 1193 | */ |
328f5751 | 1194 | int GetColumn() const; |
23324ae1 FM |
1195 | |
1196 | /** | |
1197 | The data. | |
1198 | */ | |
328f5751 | 1199 | long GetData() const; |
23324ae1 FM |
1200 | |
1201 | /** | |
1202 | The image. | |
1203 | */ | |
328f5751 | 1204 | int GetImage() const; |
23324ae1 FM |
1205 | |
1206 | /** | |
1207 | The item index. | |
1208 | */ | |
328f5751 | 1209 | long GetIndex() const; |
23324ae1 FM |
1210 | |
1211 | /** | |
1212 | An item object, used by some events. See also wxListCtrl::SetItem. | |
1213 | */ | |
5267aefd | 1214 | const wxListItem& GetItem() const; |
23324ae1 FM |
1215 | |
1216 | /** | |
1217 | Key code if the event is a keypress event. | |
1218 | */ | |
328f5751 | 1219 | int GetKeyCode() const; |
23324ae1 FM |
1220 | |
1221 | /** | |
1222 | The (new) item label for @c EVT_LIST_END_LABEL_EDIT event. | |
1223 | */ | |
5267aefd | 1224 | const wxString& GetLabel() const; |
23324ae1 FM |
1225 | |
1226 | /** | |
1227 | The mask. | |
1228 | */ | |
328f5751 | 1229 | long GetMask() const; |
23324ae1 FM |
1230 | |
1231 | /** | |
1232 | The position of the mouse pointer if the event is a drag event. | |
1233 | */ | |
328f5751 | 1234 | wxPoint GetPoint() const; |
23324ae1 FM |
1235 | |
1236 | /** | |
1237 | The text. | |
1238 | */ | |
5267aefd | 1239 | const wxString& GetText() const; |
23324ae1 FM |
1240 | |
1241 | /** | |
320ab87c FM |
1242 | This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and |
1243 | returns @true if it the label editing has been cancelled by the user | |
1244 | (GetLabel() returns an empty string in this case but it doesn't allow the | |
1245 | application to distinguish between really cancelling the edit and the | |
1246 | admittedly rare case when the user wants to rename it to an empty string). | |
23324ae1 | 1247 | */ |
328f5751 | 1248 | bool IsEditCancelled() const; |
23324ae1 FM |
1249 | }; |
1250 | ||
1251 | ||
e54c96f1 | 1252 | |
23324ae1 FM |
1253 | /** |
1254 | @class wxListItemAttr | |
7c913512 | 1255 | |
320ab87c | 1256 | Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem. |
7c913512 | 1257 | |
23324ae1 | 1258 | @library{wxbase} |
3c99e2fd | 1259 | @category{data} |
7c913512 | 1260 | |
320ab87c | 1261 | @see @ref overview_listctrl, wxListCtrl, wxListItem |
23324ae1 | 1262 | */ |
7c913512 | 1263 | class wxListItemAttr |
23324ae1 FM |
1264 | { |
1265 | public: | |
1d7c0c08 RR |
1266 | /** |
1267 | Default Constructor. | |
1268 | */ | |
1269 | wxListItemAttr(); | |
320ab87c | 1270 | |
23324ae1 FM |
1271 | /** |
1272 | Construct a wxListItemAttr with the specified foreground and | |
1273 | background colors and font. | |
1274 | */ | |
0a98423e FM |
1275 | wxListItemAttr(const wxColour& colText, |
1276 | const wxColour& colBack, | |
1277 | const wxFont& font); | |
23324ae1 FM |
1278 | |
1279 | /** | |
1280 | Returns the currently set background color. | |
1281 | */ | |
320ab87c | 1282 | const wxColour& GetBackgroundColour() const; |
23324ae1 FM |
1283 | |
1284 | /** | |
1285 | Returns the currently set font. | |
1286 | */ | |
320ab87c | 1287 | const wxFont& GetFont() const; |
23324ae1 FM |
1288 | |
1289 | /** | |
1290 | Returns the currently set text color. | |
1291 | */ | |
320ab87c | 1292 | const wxColour& GetTextColour() const; |
23324ae1 FM |
1293 | |
1294 | /** | |
1295 | Returns @true if the currently set background color is valid. | |
1296 | */ | |
328f5751 | 1297 | bool HasBackgroundColour() const; |
23324ae1 FM |
1298 | |
1299 | /** | |
1300 | Returns @true if the currently set font is valid. | |
1301 | */ | |
328f5751 | 1302 | bool HasFont() const; |
23324ae1 FM |
1303 | |
1304 | /** | |
1305 | Returns @true if the currently set text color is valid. | |
1306 | */ | |
328f5751 | 1307 | bool HasTextColour() const; |
23324ae1 FM |
1308 | |
1309 | /** | |
1310 | Sets a new background color. | |
1311 | */ | |
1312 | void SetBackgroundColour(const wxColour& colour); | |
1313 | ||
1314 | /** | |
1315 | Sets a new font. | |
1316 | */ | |
1317 | void SetFont(const wxFont& font); | |
1318 | ||
1319 | /** | |
1320 | Sets a new text color. | |
1321 | */ | |
1322 | void SetTextColour(const wxColour& colour); | |
1323 | }; | |
1324 | ||
1325 | ||
e54c96f1 | 1326 | |
23324ae1 FM |
1327 | /** |
1328 | @class wxListView | |
7c913512 FM |
1329 | |
1330 | This class currently simply presents a simpler to use interface for the | |
320ab87c FM |
1331 | wxListCtrl -- it can be thought of as a @e façade for that complicated class. |
1332 | ||
1333 | Using it is preferable to using wxListCtrl directly whenever possible because | |
1334 | in the future some ports might implement wxListView but not the full set of | |
1335 | wxListCtrl features. | |
7c913512 | 1336 | |
320ab87c FM |
1337 | Other than different interface, this class is identical to wxListCtrl. |
1338 | In particular, it uses the same events, same window styles and so on. | |
7c913512 | 1339 | |
23324ae1 FM |
1340 | @library{wxcore} |
1341 | @category{ctrl} | |
7e59b885 | 1342 | @appearance{listview.png} |
7c913512 | 1343 | |
e54c96f1 | 1344 | @see wxListView::SetColumnImage |
23324ae1 FM |
1345 | */ |
1346 | class wxListView : public wxListCtrl | |
1347 | { | |
1348 | public: | |
1349 | /** | |
1350 | Resets the column image -- after calling this function, no image will be shown. | |
3c4f71cc | 1351 | |
7c913512 | 1352 | @param col |
4cc4bfaf | 1353 | the column to clear image for |
3c4f71cc | 1354 | |
4cc4bfaf | 1355 | @see SetColumnImage() |
23324ae1 FM |
1356 | */ |
1357 | void ClearColumnImage(int col); | |
1358 | ||
1359 | /** | |
320ab87c | 1360 | Sets focus to the item with the given @a index. |
23324ae1 FM |
1361 | */ |
1362 | void Focus(long index); | |
1363 | ||
1364 | /** | |
1365 | Returns the first selected item in a (presumably) multiple selection control. | |
320ab87c FM |
1366 | Together with GetNextSelected() it can be used to iterate over all selected |
1367 | items in the control. | |
3c4f71cc | 1368 | |
d29a9a8a | 1369 | @return The first selected item, if any, -1 otherwise. |
23324ae1 | 1370 | */ |
328f5751 | 1371 | long GetFirstSelected() const; |
23324ae1 FM |
1372 | |
1373 | /** | |
1374 | Returns the currently focused item or -1 if none. | |
3c4f71cc | 1375 | |
4cc4bfaf | 1376 | @see IsSelected(), Focus() |
23324ae1 | 1377 | */ |
328f5751 | 1378 | long GetFocusedItem() const; |
23324ae1 FM |
1379 | |
1380 | /** | |
320ab87c FM |
1381 | Used together with GetFirstSelected() to iterate over all selected items |
1382 | in the control. | |
3c4f71cc | 1383 | |
320ab87c | 1384 | @return Returns the next selected item or -1 if there are no more of them. |
23324ae1 | 1385 | */ |
328f5751 | 1386 | long GetNextSelected(long item) const; |
23324ae1 FM |
1387 | |
1388 | /** | |
4cc4bfaf | 1389 | Returns @true if the item with the given @a index is selected, |
23324ae1 | 1390 | @false otherwise. |
3c4f71cc | 1391 | |
4cc4bfaf | 1392 | @see GetFirstSelected(), GetNextSelected() |
23324ae1 | 1393 | */ |
328f5751 | 1394 | bool IsSelected(long index) const; |
23324ae1 FM |
1395 | |
1396 | /** | |
1397 | Selects or unselects the given item. | |
3c4f71cc | 1398 | |
7c913512 | 1399 | @param n |
4cc4bfaf | 1400 | the item to select or unselect |
7c913512 | 1401 | @param on |
4cc4bfaf | 1402 | if @true (default), selects the item, otherwise unselects it |
3c4f71cc | 1403 | |
4cc4bfaf | 1404 | @see wxListCtrl::SetItemState |
23324ae1 | 1405 | */ |
792255cc | 1406 | void Select(long n, bool on = true); |
23324ae1 FM |
1407 | |
1408 | /** | |
320ab87c FM |
1409 | Sets the column image for the specified column. |
1410 | To use the column images, the control must have a valid image list with | |
1411 | at least one image. | |
3c4f71cc | 1412 | |
7c913512 | 1413 | @param col |
4cc4bfaf | 1414 | the column to set image for |
7c913512 | 1415 | @param image |
4cc4bfaf | 1416 | the index of the column image in the controls image list |
23324ae1 FM |
1417 | */ |
1418 | void SetColumnImage(int col, int image); | |
1419 | }; | |
1420 | ||
1421 | ||
320ab87c FM |
1422 | /** |
1423 | Column format (MSW only except wxLIST_FORMAT_LEFT). | |
1424 | */ | |
1425 | enum wxListColumnFormat | |
1426 | { | |
1427 | wxLIST_FORMAT_LEFT, | |
1428 | wxLIST_FORMAT_RIGHT, | |
1429 | wxLIST_FORMAT_CENTRE, | |
1430 | wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE | |
1431 | }; | |
e54c96f1 | 1432 | |
23324ae1 FM |
1433 | /** |
1434 | @class wxListItem | |
7c913512 | 1435 | |
23324ae1 | 1436 | This class stores information about a wxListCtrl item or column. |
7c913512 | 1437 | |
320ab87c FM |
1438 | wxListItem is a class which contains informations about: |
1439 | - Zero based item position; see SetId() and GetId(). | |
1440 | - Zero based column index; see SetColumn() and GetColumn(). | |
1441 | - The label (or header for columns); see SetText() and GetText(). | |
1442 | - The zero based index into an image list; see GetImage() and SetImage(). | |
1443 | - Application defined data; see SetData() and GetData(). | |
1444 | - For columns only: the width of the column; see SetWidth() and GetWidth(). | |
1445 | - For columns only: the format of the column; one of @c wxLIST_FORMAT_LEFT, | |
1446 | @c wxLIST_FORMAT_RIGHT, @c wxLIST_FORMAT_CENTRE. See SetAlign() and GetAlign(). | |
1447 | - The state of the item; see SetState() and GetState(). | |
1448 | This is a bitlist of the following flags: | |
1449 | - @c wxLIST_STATE_FOCUSED: The item has the focus. | |
1450 | - @c wxLIST_STATE_SELECTED: The item is selected. | |
1451 | - @c wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only. | |
1452 | - @c wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only. | |
1453 | - @c wxLIST_STATE_CUT: The item is in the cut state. Win32 only. | |
1454 | - A mask indicating which state flags are valid; this is a bitlist of the | |
1455 | flags reported above for the item state. See SetStateMask() and GetStateMask(). | |
1456 | - A mask indicating which fields of this class are valid; see SetMask() and GetMask(). | |
1457 | This is a bitlist of the following flags: | |
1458 | - @c wxLIST_MASK_STATE: The state field is valid. | |
1459 | - @c wxLIST_MASK_TEXT: The label field is valid. | |
1460 | - @c wxLIST_MASK_IMAGE: The image field is valid. | |
1461 | - @c wxLIST_MASK_DATA: The application-defined data field is valid. | |
1462 | - @c wxLIST_MASK_WIDTH: The column width field is valid. | |
1463 | - @c wxLIST_MASK_FORMAT: The column format field is valid. | |
1464 | ||
1465 | The wxListItem object can also contain item-specific colour and font | |
1466 | information: for this you need to call one of SetTextColour(), SetBackgroundColour() | |
1467 | or SetFont() functions on it passing it the colour/font to use. | |
1468 | If the colour/font is not specified, the default list control colour/font is used. | |
1469 | ||
23324ae1 | 1470 | @library{wxbase} |
3c99e2fd | 1471 | @category{data} |
320ab87c FM |
1472 | |
1473 | @see wxListCtrl | |
23324ae1 FM |
1474 | */ |
1475 | class wxListItem : public wxObject | |
1476 | { | |
1477 | public: | |
1478 | /** | |
1479 | Constructor. | |
1480 | */ | |
1481 | wxListItem(); | |
1482 | ||
1483 | /** | |
1484 | Resets the item state to the default. | |
1485 | */ | |
1486 | void Clear(); | |
1487 | ||
1488 | /** | |
320ab87c FM |
1489 | Returns the alignment for this item. |
1490 | Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or @c wxLIST_FORMAT_CENTRE. | |
23324ae1 | 1491 | */ |
328f5751 | 1492 | wxListColumnFormat GetAlign() const; |
23324ae1 FM |
1493 | |
1494 | /** | |
1495 | Returns the background colour for this item. | |
1496 | */ | |
328f5751 | 1497 | wxColour GetBackgroundColour() const; |
23324ae1 FM |
1498 | |
1499 | /** | |
1500 | Returns the zero-based column; meaningful only in report mode. | |
1501 | */ | |
328f5751 | 1502 | int GetColumn() const; |
23324ae1 FM |
1503 | |
1504 | /** | |
320ab87c FM |
1505 | Returns client data associated with the control. |
1506 | Please note that client data is associated with the item and not with subitems. | |
23324ae1 | 1507 | */ |
5267aefd | 1508 | wxUIntPtr GetData() const; |
23324ae1 FM |
1509 | |
1510 | /** | |
1511 | Returns the font used to display the item. | |
1512 | */ | |
328f5751 | 1513 | wxFont GetFont() const; |
23324ae1 FM |
1514 | |
1515 | /** | |
1516 | Returns the zero-based item position. | |
1517 | */ | |
328f5751 | 1518 | long GetId() const; |
23324ae1 FM |
1519 | |
1520 | /** | |
320ab87c FM |
1521 | Returns the zero-based index of the image associated with the item into |
1522 | the image list. | |
23324ae1 | 1523 | */ |
328f5751 | 1524 | int GetImage() const; |
23324ae1 FM |
1525 | |
1526 | /** | |
320ab87c | 1527 | Returns a bit mask indicating which fields of the structure are valid. |
3c4f71cc | 1528 | |
320ab87c FM |
1529 | Can be any combination of the following values: |
1530 | - wxLIST_MASK_STATE: @b GetState is valid. | |
1531 | - wxLIST_MASK_TEXT: @b GetText is valid. | |
1532 | - wxLIST_MASK_IMAGE: @b GetImage is valid. | |
1533 | - wxLIST_MASK_DATA: @b GetData is valid. | |
1534 | - wxLIST_MASK_WIDTH: @b GetWidth is valid. | |
1535 | - wxLIST_MASK_FORMAT: @b GetFormat is valid. | |
23324ae1 | 1536 | */ |
328f5751 | 1537 | long GetMask() const; |
23324ae1 FM |
1538 | |
1539 | /** | |
320ab87c | 1540 | Returns a bit field representing the state of the item. |
3c4f71cc | 1541 | |
320ab87c FM |
1542 | Can be any combination of: |
1543 | - wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only. | |
1544 | - wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only. | |
1545 | - wxLIST_STATE_FOCUSED: The item has the focus. | |
1546 | - wxLIST_STATE_SELECTED: The item is selected. | |
1547 | - wxLIST_STATE_CUT: The item is in the cut state. Win32 only. | |
23324ae1 | 1548 | */ |
328f5751 | 1549 | long GetState() const; |
23324ae1 FM |
1550 | |
1551 | /** | |
1552 | Returns the label/header text. | |
1553 | */ | |
320ab87c | 1554 | const wxString& GetText() const; |
23324ae1 FM |
1555 | |
1556 | /** | |
1557 | Returns the text colour. | |
1558 | */ | |
328f5751 | 1559 | wxColour GetTextColour() const; |
23324ae1 FM |
1560 | |
1561 | /** | |
1562 | Meaningful only for column headers in report mode. Returns the column width. | |
1563 | */ | |
328f5751 | 1564 | int GetWidth() const; |
23324ae1 FM |
1565 | |
1566 | /** | |
320ab87c | 1567 | Sets the alignment for the item. See also GetAlign() |
23324ae1 FM |
1568 | */ |
1569 | void SetAlign(wxListColumnFormat align); | |
1570 | ||
1571 | /** | |
1572 | Sets the background colour for the item. | |
1573 | */ | |
1574 | void SetBackgroundColour(const wxColour& colBack); | |
1575 | ||
1576 | /** | |
1577 | Sets the zero-based column. Meaningful only in report mode. | |
1578 | */ | |
1579 | void SetColumn(int col); | |
1580 | ||
1581 | //@{ | |
1582 | /** | |
320ab87c FM |
1583 | Sets client data for the item. |
1584 | Please note that client data is associated with the item and not with subitems. | |
23324ae1 FM |
1585 | */ |
1586 | void SetData(long data); | |
7c913512 | 1587 | void SetData(void* data); |
23324ae1 FM |
1588 | //@} |
1589 | ||
1590 | /** | |
1591 | Sets the font for the item. | |
1592 | */ | |
1593 | void SetFont(const wxFont& font); | |
1594 | ||
1595 | /** | |
1596 | Sets the zero-based item position. | |
1597 | */ | |
1598 | void SetId(long id); | |
1599 | ||
1600 | /** | |
1601 | Sets the zero-based index of the image associated with the item | |
1602 | into the image list. | |
1603 | */ | |
1604 | void SetImage(int image); | |
1605 | ||
1606 | /** | |
1607 | Sets the mask of valid fields. See GetMask(). | |
1608 | */ | |
1609 | void SetMask(long mask); | |
1610 | ||
1611 | /** | |
1612 | Sets the item state flags (note that the valid state flags are influenced | |
320ab87c FM |
1613 | by the value of the state mask, see wxListItem::SetStateMask). |
1614 | ||
1615 | See GetState() for valid flag values. | |
23324ae1 FM |
1616 | */ |
1617 | void SetState(long state); | |
1618 | ||
1619 | /** | |
1620 | Sets the bitmask that is used to determine which of the state flags | |
1621 | are to be set. See also SetState(). | |
1622 | */ | |
1623 | void SetStateMask(long stateMask); | |
1624 | ||
1625 | /** | |
1626 | Sets the text label for the item. | |
1627 | */ | |
1628 | void SetText(const wxString& text); | |
1629 | ||
1630 | /** | |
1631 | Sets the text colour for the item. | |
1632 | */ | |
1633 | void SetTextColour(const wxColour& colText); | |
1634 | ||
1635 | /** | |
1636 | Meaningful only for column headers in report mode. Sets the column width. | |
1637 | */ | |
1638 | void SetWidth(int width); | |
1639 | }; | |
e54c96f1 | 1640 |