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