Use /bin/echo for creation of Mac OS X PkgInfo files.
[wxWidgets.git] / interface / wx / listctrl.h
CommitLineData
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*/
158class wxListCtrl : public wxControl
159{
160public:
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
1037protected:
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*/
1167class wxListEvent : public wxNotifyEvent
1168{
1169public:
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 1263class wxListItemAttr
23324ae1
FM
1264{
1265public:
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*/
1346class wxListView : public wxListCtrl
1347{
1348public:
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*/
1425enum 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*/
1475class wxListItem : public wxObject
1476{
1477public:
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