1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxListCtrl
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
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.
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
22 wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText
23 (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
24 wxListCtrl::OnGetItemAttr) to return the information about the items when the
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
34 Using many of wxListCtrl features is shown in the
35 @ref page_samples_listctrl "corresponding sample".
37 To intercept events from a list control, use the event table macros described
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
43 the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1.
48 Multicolumn list view, with optional small icons. Columns are
49 computed automatically, i.e. you don't set columns as in
50 @c wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
52 Single or multicolumn report view, with optional header.
54 The application provides items text on demand. May only be used
57 Large icon view, with optional labels.
58 @style{wxLC_SMALL_ICON}
59 Small icon view, with optional labels.
60 @style{wxLC_ALIGN_TOP}
61 Icons align to the top. Win32 default, Win32 only.
62 @style{wxLC_ALIGN_LEFT}
63 Icons align to the left.
64 @style{wxLC_AUTOARRANGE}
65 Icons arrange themselves. Win32 only.
66 @style{wxLC_EDIT_LABELS}
67 Labels are editable: the application will be notified when editing
69 @style{wxLC_NO_HEADER}
70 No header in report mode.
71 @style{wxLC_SINGLE_SEL}
72 Single selection (default is multiple).
73 @style{wxLC_SORT_ASCENDING}
74 Sort in ascending order. (You must still supply a comparison callback
75 in wxListCtrl::SortItems.)
76 @style{wxLC_SORT_DESCENDING}
77 Sort in descending order. (You must still supply a comparison callback
78 in wxListCtrl::SortItems.)
80 Draws light horizontal rules between rows in report mode.
82 Draws light vertical rules between columns in report mode.
86 @beginEventEmissionTable{wxListEvent}
87 @event{EVT_LIST_BEGIN_DRAG(id, func)}
88 Begin dragging with the left mouse button.
89 @event{EVT_LIST_BEGIN_RDRAG(id, func)}
90 Begin dragging with the right mouse button..
91 @event{EVT_BEGIN_LABEL_EDIT(id, func)}
92 Begin editing a label. This can be prevented by calling Veto().
93 @event{EVT_LIST_END_LABEL_EDIT(id, func)}
94 Finish editing a label. This can be prevented by calling Veto().
95 @event{EVT_LIST_DELETE_ITEM(id, func)}
97 @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
98 All items were deleted.
99 @event{EVT_LIST_ITEM_SELECTED(id, func)}
100 The item has been selected.
101 @event{EVT_LIST_ITEM_DESELECTED(id, func)}
102 The item has been deselected.
103 @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
104 The item has been activated (ENTER or double click).
105 @event{EVT_LIST_ITEM_FOCUSED(id, func)}
106 The currently focused item has changed.
107 @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
108 The middle mouse button has been clicked on an item.
109 @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
110 The right mouse button has been clicked on an item.
111 @event{EVT_LIST_KEY_DOWN(id, func)}
112 A key has been pressed.
113 @event{EVT_LIST_INSERT_ITEM(id, func)}
114 An item has been inserted.
115 @event{EVT_LIST_COL_CLICK(id, func)}
116 A column (m_col) has been left-clicked.
117 @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
118 A column (m_col) has been right-clicked.
119 @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
120 The user started resizing a column - can be vetoed.
121 @event{EVT_LIST_COL_DRAGGING(id, func)}
122 The divider between columns is being dragged.
123 @event{EVT_LIST_COL_END_DRAG(id, func)}
124 A column has been resized by the user.
125 @event{EVT_LIST_CACHE_HINT(id, func)}
126 Prepare cache for a virtual list control.
132 @appearance{listctrl.png}
134 @see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList,
135 wxListEvent, wxListItem, wxEditableListBox
137 class wxListCtrl
: public wxControl
146 Constructor, creating and showing a list control.
149 Parent window. Must not be @NULL.
151 Window identifier. The value wxID_ANY indicates a default value.
154 If ::wxDefaultPosition is specified then a default position is chosen.
157 If ::wxDefaultSize is specified then the window is sized appropriately.
159 Window style. See wxListCtrl.
165 @see Create(), wxValidator
167 wxListCtrl(wxWindow
* parent
, wxWindowID id
,
168 const wxPoint
& pos
= wxDefaultPosition
,
169 const wxSize
& size
= wxDefaultSize
,
170 long style
= wxLC_ICON
,
171 const wxValidator
& validator
= wxDefaultValidator
,
172 const wxString
& name
= wxListCtrlNameStr
);
175 Destructor, destroying the list control.
177 virtual ~wxListCtrl();
180 Arranges the items in icon or small icon view.
181 This only has effect on Win32. @a flag is one of:
182 - wxLIST_ALIGN_DEFAULT: Default alignment.
183 - wxLIST_ALIGN_LEFT: Align to the left side of the control.
184 - wxLIST_ALIGN_TOP: Align to the top side of the control.
185 - wxLIST_ALIGN_SNAP_TO_GRID: Snap to grid.
187 bool Arrange(int flag
= wxLIST_ALIGN_DEFAULT
);
190 Sets the image list associated with the control and takes ownership of it
191 (i.e. the control will, unlike when using SetImageList(), delete the list
192 when destroyed). @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
193 @c wxIMAGE_LIST_STATE (the last is unimplemented).
197 void AssignImageList(wxImageList
* imageList
, int which
);
200 Deletes all items and all columns.
205 Creates the list control. See wxListCtrl() for further details.
207 bool Create(wxWindow
* parent
, wxWindowID id
,
208 const wxPoint
& pos
= wxDefaultPosition
,
209 const wxSize
& size
= wxDefaultSize
,
210 long style
= wxLC_ICON
,
211 const wxValidator
& validator
= wxDefaultValidator
,
212 const wxString
& name
= wxListCtrlNameStr
);
215 Deletes all items in the list control.
217 @note This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM
218 event because deleting many items from the control would be too slow
219 then (unlike wxListCtrl::DeleteItem).
221 bool DeleteAllItems();
226 bool DeleteColumn(int col
);
229 Deletes the specified item.
230 This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the
233 @see DeleteAllItems()
235 bool DeleteItem(long item
);
238 Starts editing the label of the given item.
240 This function generates a @c EVT_LIST_BEGIN_LABEL_EDIT event which can be
241 vetoed so that no text control will appear for in-place editing.
243 If the user changed the label (i.e. s/he does not press ESC or leave
244 the text control without changes, a @c EVT_LIST_END_LABEL_EDIT event
245 will be sent which can be vetoed as well.
247 wxTextCtrl
* EditLabel(long item
,
248 wxClassInfo
* textControlClass
= CLASSINFO(wxTextCtrl
));
251 Ensures this item is visible.
253 bool EnsureVisible(long item
);
256 Find an item whose label matches this string, starting from start or the
257 beginning if start is @c -1. The string comparison is case insensitive.
259 If @a partial is @true then this method will look for items which begin with @a str.
261 @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
263 long FindItem(long start
, const wxString
& str
,
264 bool partial
= false);
267 Find an item whose data matches this data, starting from start or the
268 beginning if 'start' is @c -1.
271 In wxPerl this method is implemented as FindItemData(start, data).
274 @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
276 long FindItem(long start
, wxUIntPtr data
);
279 Find an item nearest this position in the specified direction,
280 starting from @a start or the beginning if @a start is -1.
283 In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
286 @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
288 long FindItem(long start
, const wxPoint
& pt
, int direction
);
291 Gets information about this column.
292 See SetItem() for more information.
295 In wxPerl this method takes only the @a col parameter and
296 returns a @c Wx::ListItem (or @c undef).
299 bool GetColumn(int col
, wxListItem
& item
) const;
302 Returns the number of columns.
304 int GetColumnCount() const;
307 Gets the column index from its position in visual order.
309 After calling SetColumnsOrder(), the index returned by this function
310 corresponds to the value of the element number @a pos in the array
311 returned by GetColumnsOrder().
313 Please see SetColumnsOrder() documentation for an example and
314 additional remarks about the columns ordering.
316 @see GetColumnOrder()
318 int GetColumnIndexFromOrder(int pos
) const;
321 Gets the column visual order position.
323 This function returns the index of the column which appears at the
324 given visual position, e.g. calling it with @a col equal to 0 returns
325 the index of the first shown column.
327 Please see SetColumnsOrder() documentation for an example and
328 additional remarks about the columns ordering.
330 @see GetColumnsOrder(), GetColumnIndexFromOrder()
332 int GetColumnOrder(int col
) const;
335 Gets the column width (report view only).
337 int GetColumnWidth(int col
) const;
340 Returns the array containing the orders of all columns.
342 On error, an empty array is returned.
344 Please see SetColumnsOrder() documentation for an example and
345 additional remarks about the columns ordering.
347 @see GetColumnOrder(), GetColumnIndexFromOrder()
349 wxArrayInt
GetColumnsOrder() const;
352 Gets the number of items that can fit vertically in the visible area of
353 the list control (list or report view) or the total number of items in
354 the list control (icon or small icon view).
356 int GetCountPerPage() const;
359 Returns the edit control being currently used to edit a label.
360 Returns @NULL if no label is being edited.
362 @note It is currently only implemented for wxMSW and the generic version,
363 not for the native Mac OS X version.
365 wxTextCtrl
* GetEditControl() const;
368 Returns the specified image list. @a which may be one of:
369 - wxIMAGE_LIST_NORMAL: The normal (large icon) image list.
370 - wxIMAGE_LIST_SMALL: The small icon image list.
371 - wxIMAGE_LIST_STATE: The user-defined state image list (unimplemented).
373 wxImageList
* GetImageList(int which
) const;
376 Gets information about the item. See SetItem() for more information.
378 You must call @e info.SetId() to set the ID of item you're interested in
379 before calling this method, and @e info.SetMask() with the flags indicating
380 what fields you need to retrieve from @a info.
383 In wxPerl this method takes as parameter the ID of the item
384 and (optionally) the column, and returns a Wx::ListItem object.
387 bool GetItem(wxListItem
& info
) const;
390 Returns the colour for this item.
391 If the item has no specific colour, returns an invalid colour
392 (and not the default background control of the control itself).
394 @see GetItemTextColour()
396 wxColour
GetItemBackgroundColour(long item
) const;
399 Returns the number of items in the list control.
401 int GetItemCount() const;
404 Gets the application-defined data associated with this item.
406 wxUIntPtr
GetItemData(long item
) const;
409 Returns the item's font.
411 wxFont
GetItemFont(long item
) const;
414 Returns the position of the item, in icon or small icon view.
417 In wxPerl this method takes only the @a item parameter and
418 returns a @c Wx::Point (or @c undef).
421 bool GetItemPosition(long item
, wxPoint
& pos
) const;
424 Returns the rectangle representing the item's size and position, in physical
427 @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
430 In wxPerl this method takes only the @a item and @a code parameters and
431 returns a @c Wx::Rect (or @c undef).
434 bool GetItemRect(long item
, wxRect
& rect
,
435 int code
= wxLIST_RECT_BOUNDS
) const;
438 Retrieves the spacing between icons in pixels: horizontal spacing is
439 returned as @c x component of the wxSize object and the vertical spacing
440 as its @c y component.
442 wxSize
GetItemSpacing() const;
445 Gets the item state. For a list of state flags, see SetItem().
446 The @a stateMask indicates which state flags are of interest.
448 int GetItemState(long item
, long stateMask
) const;
451 Gets the item text for this item.
454 Item (zero-based) index.
456 Item column (zero-based) index. Column 0 is the default. This
457 parameter is new in wxWidgets 2.9.1.
459 wxString
GetItemText(long item
, int col
= 0) const;
462 Returns the colour for this item.
464 If the item has no specific colour, returns an invalid colour (and not the
465 default foreground control of the control itself as this wouldn't allow
466 distinguishing between items having the same colour as the current control
467 foreground and items with default colour which, hence, have always the
468 same colour as the control).
470 wxColour
GetItemTextColour(long item
) const;
473 Searches for an item with the given geometry or state, starting from
474 @a item but excluding the @a item itself.
476 If @a item is -1, the first item that matches the specified flags will be returned.
477 Returns the first item with given state following @a item or -1 if no such item found.
478 This function may be used to find all selected items in the control like this:
484 item = listctrl->GetNextItem(item,
486 wxLIST_STATE_SELECTED);
490 // this item is selected - do whatever is needed with it
491 wxLogMessage("Item %ld is selected.", item);
495 @a geometry can be one of:
496 - wxLIST_NEXT_ABOVE: Searches for an item above the specified item.
497 - wxLIST_NEXT_ALL: Searches for subsequent item by index.
498 - wxLIST_NEXT_BELOW: Searches for an item below the specified item.
499 - wxLIST_NEXT_LEFT: Searches for an item to the left of the specified item.
500 - wxLIST_NEXT_RIGHT: Searches for an item to the right of the specified item.
502 @note this parameter is only supported by wxMSW currently and ignored on
505 @a state can be a bitlist of the following:
506 - wxLIST_STATE_DONTCARE: Don't care what the state is.
507 - wxLIST_STATE_DROPHILITED: The item indicates it is a drop target.
508 - wxLIST_STATE_FOCUSED: The item has the focus.
509 - wxLIST_STATE_SELECTED: The item is selected.
510 - wxLIST_STATE_CUT: The item is selected as part of a cut and paste operation.
512 long GetNextItem(long item
, int geometry
= wxLIST_NEXT_ALL
,
513 int state
= wxLIST_STATE_DONTCARE
) const;
516 Returns the number of selected items in the list control.
518 int GetSelectedItemCount() const;
521 Returns the rectangle representing the size and position, in physical
522 coordinates, of the given subitem, i.e. the part of the row @a item in the
525 This method is only meaningfull when the wxListCtrl is in the report mode.
526 If @a subItem parameter is equal to the special value
527 @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
530 @a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or
531 @c wxLIST_RECT_LABEL.
535 bool GetSubItemRect(long item
, long subItem
, wxRect
& rect
,
536 int code
= wxLIST_RECT_BOUNDS
) const;
539 Gets the text colour of the list control.
541 wxColour
GetTextColour() const;
544 Gets the index of the topmost visible item when in list or report view.
546 long GetTopItem() const;
549 Returns the rectangle taken by all items in the control. In other words, if the
550 controls client size were equal to the size of this rectangle, no scrollbars
551 would be needed and no free space would be left.
553 Note that this function only works in the icon and small icon views, not in
554 list or report views (this is a limitation of the native Win32 control).
556 wxRect
GetViewRect() const;
559 Determines which item (if any) is at the specified point, giving details
560 in @a flags. Returns index of the item or @c wxNOT_FOUND if no item is at
563 @a flags will be a combination of the following flags:
564 - wxLIST_HITTEST_ABOVE: Above the client area.
565 - wxLIST_HITTEST_BELOW: Below the client area.
566 - wxLIST_HITTEST_NOWHERE: In the client area but below the last item.
567 - wxLIST_HITTEST_ONITEMICON: On the bitmap associated with an item.
568 - wxLIST_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
569 - wxLIST_HITTEST_ONITEMRIGHT: In the area to the right of an item.
570 - wxLIST_HITTEST_ONITEMSTATEICON: On the state icon for a tree view item
571 that is in a user-defined state.
572 - wxLIST_HITTEST_TOLEFT: To the right of the client area.
573 - wxLIST_HITTEST_TORIGHT: To the left of the client area.
574 - wxLIST_HITTEST_ONITEM: Combination of @c wxLIST_HITTEST_ONITEMICON,
575 @c wxLIST_HITTEST_ONITEMLABEL, @c wxLIST_HITTEST_ONITEMSTATEICON.
577 If @a ptrSubItem is not @NULL and the wxListCtrl is in the report
578 mode the subitem (or column) number will also be provided.
579 This feature is only available in version 2.7.0 or higher and is currently only
580 implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on
581 the host system or the value stored in @a ptrSubItem will be always -1.
582 To compile this feature into wxWidgets library you need to have access to
583 commctrl.h of version 4.70 that is provided by Microsoft.
586 In wxPerl this method only takes the @a point parameter
587 and returns a 2-element list (item, flags).
590 long HitTest(const wxPoint
& point
, int& flags
, long* ptrSubItem
= NULL
) const;
593 For report view mode (only), inserts a column. For more details, see SetItem().
595 long InsertColumn(long col
, wxListItem
& info
);
598 For report view mode (only), inserts a column. For more details, see SetItem().
600 long InsertColumn(long col
, const wxString
& heading
,
601 int format
= wxLIST_FORMAT_LEFT
,
605 Inserts an item, returning the index of the new item if successful, -1 otherwise.
610 long InsertItem(wxListItem
& info
);
613 Insert an string item.
616 Index of the new item, supplied by the application
621 In wxPerl this method is implemented as InsertStringItem(index, label).
624 long InsertItem(long index
, const wxString
& label
);
627 Insert an image item.
630 Index of the new item, supplied by the application
632 Index into the image list associated with this control and view style
635 In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
638 long InsertItem(long index
, int imageIndex
);
641 Insert an image/string item.
644 Index of the new item, supplied by the application
648 Index into the image list associated with this control and view style
651 In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
654 long InsertItem(long index
, const wxString
& label
,
658 Redraws the given @e item.
660 This is only useful for the virtual list controls as without calling this
661 function the displayed value of the item doesn't change even when the
662 underlying data does change.
666 void RefreshItem(long item
);
669 Redraws the items between @a itemFrom and @e itemTo.
670 The starting item must be less than or equal to the ending one.
672 Just as RefreshItem() this is only useful for virtual list controls.
674 void RefreshItems(long itemFrom
, long itemTo
);
677 Scrolls the list control. If in icon, small icon or report view mode,
678 @a dx specifies the number of pixels to scroll. If in list view mode,
679 @a dx specifies the number of columns to scroll. @a dy always specifies
680 the number of pixels to scroll vertically.
682 @note This method is currently only implemented in the Windows version.
684 bool ScrollList(int dx
, int dy
);
687 Sets the background colour.
689 Note that the wxWindow::GetBackgroundColour() function of wxWindow base
690 class can be used to retrieve the current background colour.
692 virtual bool SetBackgroundColour(const wxColour
& col
);
695 Sets information about this column.
696 See SetItem() for more information.
698 bool SetColumn(int col
, wxListItem
& item
);
701 Sets the column width.
703 @a width can be a width in pixels or @c wxLIST_AUTOSIZE (-1) or
704 @c wxLIST_AUTOSIZE_USEHEADER (-2).
706 @c wxLIST_AUTOSIZE will resize the column to the length of its longest item.
708 @c wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the
709 header (Win32) or 80 pixels (other platforms).
711 In small or normal icon view, @a col must be -1, and the column width is set
714 bool SetColumnWidth(int col
, int width
);
717 Changes the order in which the columns are shown.
719 By default, the columns of a list control appear on the screen in order
720 of their indices, i.e. the column 0 appears first, the column 1 next
721 and so on. However by using this function it is possible to arbitrarily
722 reorder the columns visual order and the user can also rearrange the
723 columns interactively by dragging them. In this case, the index of the
724 column is not the same as its order and the functions GetColumnOrder()
725 and GetColumnIndexFromOrder() should be used to translate between them.
726 Notice that all the other functions still work with the column indices,
727 i.e. the visual positioning of the columns on screen doesn't affect the
728 code setting or getting their values for example.
730 The @a orders array must have the same number elements as the number of
731 columns and contain each position exactly once. Its n-th element
732 contains the index of the column to be shown in n-th position, so for a
733 control with three columns passing an array with elements 2, 0 and 1
734 results in the third column being displayed first, the first one next
735 and the second one last.
739 wxListCtrl *list = new wxListCtrl(...);
740 for ( int i = 0; i < 3; i++ )
741 list->InsertColumn(i, wxString::Format("Column %d", i));
747 list->SetColumnsOrder(order);
749 // now list->GetColumnsOrder() will return order and
750 // list->GetColumnIndexFromOrder(n) will return order[n] and
751 // list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
752 // 1 and 2 respectively
755 Please notice that this function makes sense for report view only and
756 currently is only implemented in wxMSW port. To avoid explicit tests
757 for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER
758 as this will allow it to start working under the other platforms when
759 support for the column reordering is added there.
761 @see GetColumnsOrder()
763 bool SetColumnsOrder(const wxArrayInt
& orders
) const;
766 Sets the image list associated with the control.
768 @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
769 @c wxIMAGE_LIST_STATE (the last is unimplemented).
771 This method does not take ownership of the image list, you have to
774 @see AssignImageList()
776 void SetImageList(wxImageList
* imageList
, int which
);
779 Sets the data of an item.
781 Using the wxListItem's mask and state mask, you can change only selected
782 attributes of a wxListCtrl item.
784 bool SetItem(wxListItem
& info
);
787 Sets an item string field at a particular column.
789 long SetItem(long index
, int column
, const wxString
& label
, int imageId
= -1);
792 Sets the background colour for this item.
793 This function only works in report view mode.
794 The colour can be retrieved using GetItemBackgroundColour().
796 void SetItemBackgroundColour(long item
, const wxColour
& col
);
799 Sets the image associated with the item.
800 In report view, you can specify the column.
801 The image is an index into the image list associated with the list control.
803 bool SetItemColumnImage(long item
, long column
, int image
);
806 This method can only be used with virtual list controls.
808 It is used to indicate to the control the number of items it contains.
809 After calling it, the main program should be ready to handle calls to
810 various item callbacks (such as wxListCtrl::OnGetItemText) for all
811 items in the range from 0 to @a count.
813 Notice that the control is not necessarily redrawn after this call as
814 it may be undesirable if an item which is not visible on the screen
815 anyhow was added to or removed from a control displaying many items, if
816 you do need to refresh the display you can just call Refresh() manually.
818 void SetItemCount(long count
);
821 Associates application-defined data with this item.
823 Notice that this function cannot be used to associate pointers with the control
824 items, use SetItemPtrData() instead.
826 bool SetItemData(long item
, long data
);
829 Sets the item's font.
831 void SetItemFont(long item
, const wxFont
& font
);
834 Sets the unselected and selected images associated with the item.
835 The images are indices into the image list associated with the list control.
837 bool SetItemImage(long item
, int image
, int selImage
= -1);
840 Sets the unselected and selected images associated with the item.
841 The images are indices into the image list associated with the list control.
844 This form is deprecated: @a selImage is not used; use the other
845 SetItemImage() overload.
847 bool SetItemImage(long item
, int image
, int selImage
= -1);
850 Sets the position of the item, in icon or small icon view. Windows only.
852 bool SetItemPosition(long item
, const wxPoint
& pos
);
855 Associates application-defined data with this item.
857 The @a data parameter may be either an integer or a pointer cast to the
858 @c wxUIntPtr type which is guaranteed to be large enough to be able to
859 contain all integer types and pointers.
863 bool SetItemPtrData(long item
, wxUIntPtr data
);
866 Sets the item state. For a list of state flags, see SetItem().
867 The @b stateMask indicates which state flags are valid.
869 bool SetItemState(long item
, long state
, long stateMask
);
872 Sets the item text for this item.
874 void SetItemText(long item
, const wxString
& text
);
877 Sets the colour for this item.
878 This function only works in report view.
879 The colour can be retrieved using GetItemTextColour().
881 void SetItemTextColour(long item
, const wxColour
& col
);
884 Adds or removes a single window style.
886 void SetSingleStyle(long style
, bool add
= true);
889 Sets the text colour of the list control.
891 void SetTextColour(const wxColour
& col
);
894 Sets the whole window style, deleting all items.
896 void SetWindowStyleFlag(long style
);
899 Call this function to sort the items in the list control. Sorting is done
900 using the specified @a fnSortCallBack function. This function must have the
903 int wxCALLBACK wxListCompareFunction(long item1, long item2, wxIntPtr sortData)
906 It is called each time when the two items must be compared and should return 0
907 if the items are equal, negative value if the first item is less than the
908 second one and positive value if the first one is greater than the second one
909 (the same convention as used by @c qsort(3)).
911 The parameter @e item1 is the client data associated with the first item (NOT the index).
912 The parameter @e item2 is the client data associated with the second item (NOT the index).
913 The parameter @e data is the value passed to SortItems() itself.
915 Notice that the control may only be sorted on client data associated with
916 the items, so you must use SetItemData if you want to be able to sort the
917 items in the control.
919 Please see the @ref page_samples_listctrl for an example of using this function.
922 In wxPerl the comparison function must take just two parameters;
923 however, you may use a closure to achieve an effect similar to the
924 SortItems third parameter.
927 bool SortItems(wxListCtrlCompare fnSortCallBack
, wxIntPtr data
);
932 This function may be overridden in the derived class for a control with
933 @c wxLC_VIRTUAL style. It should return the attribute for the specified
934 @c item or @NULL to use the default appearance parameters.
936 wxListCtrl will not delete the pointer or keep a reference of it.
937 You can return the same wxListItemAttr pointer for every OnGetItemAttr() call.
939 The base class version always returns @NULL.
941 @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
942 OnGetItemColumnAttr()
944 virtual wxListItemAttr
* OnGetItemAttr(long item
) const;
947 This function may be overridden in the derived class for a control with
948 @c wxLC_VIRTUAL style.
950 It should return the attribute for the for the specified @a item and @a
951 column or @NULL to use the default appearance parameters.
953 The base class version returns @c OnGetItemAttr(item).
955 @note Currently this function is only called under wxMSW, the other
956 ports only support OnGetItemAttr()
958 @see OnGetItemAttr(), OnGetItemText(),
959 OnGetItemImage(), OnGetItemColumnImage(),
961 virtual wxListItemAttr
* OnGetItemColumnAttr(long item
, long column
) const;
964 Override this function in the derived class for a control with
965 @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
966 index for the given line and column.
968 The base class version always calls OnGetItemImage() for the first column, else
971 @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(),
972 OnGetItemColumnAttr()
974 virtual int OnGetItemColumnImage(long item
, long column
) const;
977 This function must be overridden in the derived class for a control with
978 @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
979 control doesn't have an image list, it is not necessary to override it).
980 It should return the index of the items image in the controls image list
983 In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
984 the first column of each line.
986 The base class version always returns -1.
988 @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
990 virtual int OnGetItemImage(long item
) const;
993 This function @b must be overridden in the derived class for a control with
994 @c wxLC_VIRTUAL style. It should return the string containing the text of
995 the given @a column for the specified @c item.
997 @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
999 virtual wxString
OnGetItemText(long item
, long column
) const;
1007 A list event holds information about events associated with wxListCtrl objects.
1009 @beginEventTable{wxListEvent}
1010 @event{EVT_LIST_BEGIN_DRAG(id, func)}
1011 Begin dragging with the left mouse button.
1012 @event{EVT_LIST_BEGIN_RDRAG(id, func)}
1013 Begin dragging with the right mouse button.
1014 @event{EVT_LIST_BEGIN_LABEL_EDIT(id, func)}
1015 Begin editing a label. This can be prevented by calling Veto().
1016 @event{EVT_LIST_END_LABEL_EDIT(id, func)}
1017 Finish editing a label. This can be prevented by calling Veto().
1018 @event{EVT_LIST_DELETE_ITEM(id, func)}
1020 @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
1022 @event{EVT_LIST_ITEM_SELECTED(id, func)}
1023 The item has been selected.
1024 @event{EVT_LIST_ITEM_DESELECTED(id, func)}
1025 The item has been deselected.
1026 @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
1027 The item has been activated (ENTER or double click).
1028 @event{EVT_LIST_ITEM_FOCUSED(id, func)}
1029 The currently focused item has changed.
1030 @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
1031 The middle mouse button has been clicked on an item.
1032 @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
1033 The right mouse button has been clicked on an item.
1034 @event{EVT_LIST_KEY_DOWN(id, func)}
1035 A key has been pressed.
1036 @event{EVT_LIST_INSERT_ITEM(id, func)}
1037 An item has been inserted.
1038 @event{EVT_LIST_COL_CLICK(id, func)}
1039 A column (m_col) has been left-clicked.
1040 @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
1041 A column (m_col) (which can be -1 if the click occurred outside any column)
1042 has been right-clicked.
1043 @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
1044 The user started resizing a column - can be vetoed.
1045 @event{EVT_LIST_COL_DRAGGING(id, func)}
1046 The divider between columns is being dragged.
1047 @event{EVT_LIST_COL_END_DRAG(id, func)}
1048 A column has been resized by the user.
1049 @event{EVT_LIST_CACHE_HINT(id, func)}
1050 Prepare cache for a virtual list control
1059 class wxListEvent
: public wxNotifyEvent
1065 wxListEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0);
1068 For @c EVT_LIST_CACHE_HINT event only: return the first item which the
1069 list control advises us to cache.
1071 long GetCacheFrom() const;
1074 For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
1075 which the list control advises us to cache.
1077 long GetCacheTo() const;
1080 The column position: it is only used with @c COL events.
1082 For the column dragging events, it is the column to the left of the divider
1083 being dragged, for the column click events it may be -1 if the user clicked
1084 in the list control header outside any column.
1086 int GetColumn() const;
1091 long GetData() const;
1096 int GetImage() const;
1101 long GetIndex() const;
1104 An item object, used by some events. See also wxListCtrl::SetItem.
1106 const wxListItem
& GetItem() const;
1109 Key code if the event is a keypress event.
1111 int GetKeyCode() const;
1114 The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
1116 const wxString
& GetLabel() const;
1121 long GetMask() const;
1124 The position of the mouse pointer if the event is a drag event.
1126 wxPoint
GetPoint() const;
1131 const wxString
& GetText() const;
1134 This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and
1135 returns @true if it the label editing has been cancelled by the user
1136 (GetLabel() returns an empty string in this case but it doesn't allow the
1137 application to distinguish between really cancelling the edit and the
1138 admittedly rare case when the user wants to rename it to an empty string).
1140 bool IsEditCancelled() const;
1146 @class wxListItemAttr
1148 Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
1153 @see @ref overview_listctrl, wxListCtrl, wxListItem
1155 class wxListItemAttr
1159 Default Constructor.
1164 Construct a wxListItemAttr with the specified foreground and
1165 background colors and font.
1167 wxListItemAttr(const wxColour
& colText
,
1168 const wxColour
& colBack
,
1169 const wxFont
& font
);
1172 Returns the currently set background color.
1174 const wxColour
& GetBackgroundColour() const;
1177 Returns the currently set font.
1179 const wxFont
& GetFont() const;
1182 Returns the currently set text color.
1184 const wxColour
& GetTextColour() const;
1187 Returns @true if the currently set background color is valid.
1189 bool HasBackgroundColour() const;
1192 Returns @true if the currently set font is valid.
1194 bool HasFont() const;
1197 Returns @true if the currently set text color is valid.
1199 bool HasTextColour() const;
1202 Sets a new background color.
1204 void SetBackgroundColour(const wxColour
& colour
);
1209 void SetFont(const wxFont
& font
);
1212 Sets a new text color.
1214 void SetTextColour(const wxColour
& colour
);
1222 This class currently simply presents a simpler to use interface for the
1223 wxListCtrl -- it can be thought of as a @e façade for that complicated class.
1225 Using it is preferable to using wxListCtrl directly whenever possible because
1226 in the future some ports might implement wxListView but not the full set of
1227 wxListCtrl features.
1229 Other than different interface, this class is identical to wxListCtrl.
1230 In particular, it uses the same events, same window styles and so on.
1234 @appearance{listview.png}
1236 @see wxListView::SetColumnImage
1238 class wxListView
: public wxListCtrl
1242 Resets the column image -- after calling this function, no image will be shown.
1245 the column to clear image for
1247 @see SetColumnImage()
1249 void ClearColumnImage(int col
);
1252 Sets focus to the item with the given @a index.
1254 void Focus(long index
);
1257 Returns the first selected item in a (presumably) multiple selection control.
1258 Together with GetNextSelected() it can be used to iterate over all selected
1259 items in the control.
1261 @return The first selected item, if any, -1 otherwise.
1263 long GetFirstSelected() const;
1266 Returns the currently focused item or -1 if none.
1268 @see IsSelected(), Focus()
1270 long GetFocusedItem() const;
1273 Used together with GetFirstSelected() to iterate over all selected items
1276 @return Returns the next selected item or -1 if there are no more of them.
1278 long GetNextSelected(long item
) const;
1281 Returns @true if the item with the given @a index is selected,
1284 @see GetFirstSelected(), GetNextSelected()
1286 bool IsSelected(long index
) const;
1289 Selects or unselects the given item.
1292 the item to select or unselect
1294 if @true (default), selects the item, otherwise unselects it
1296 @see wxListCtrl::SetItemState
1298 void Select(long n
, bool on
= true);
1301 Sets the column image for the specified column.
1302 To use the column images, the control must have a valid image list with
1306 the column to set image for
1308 the index of the column image in the controls image list
1310 void SetColumnImage(int col
, int image
);
1315 Column format (MSW only except wxLIST_FORMAT_LEFT).
1317 enum wxListColumnFormat
1320 wxLIST_FORMAT_RIGHT
,
1321 wxLIST_FORMAT_CENTRE
,
1322 wxLIST_FORMAT_CENTER
= wxLIST_FORMAT_CENTRE
1328 This class stores information about a wxListCtrl item or column.
1330 wxListItem is a class which contains informations about:
1331 - Zero based item position; see SetId() and GetId().
1332 - Zero based column index; see SetColumn() and GetColumn().
1333 - The label (or header for columns); see SetText() and GetText().
1334 - The zero based index into an image list; see GetImage() and SetImage().
1335 - Application defined data; see SetData() and GetData().
1336 - For columns only: the width of the column; see SetWidth() and GetWidth().
1337 - For columns only: the format of the column; one of @c wxLIST_FORMAT_LEFT,
1338 @c wxLIST_FORMAT_RIGHT, @c wxLIST_FORMAT_CENTRE. See SetAlign() and GetAlign().
1339 - The state of the item; see SetState() and GetState().
1340 This is a bitlist of the following flags:
1341 - @c wxLIST_STATE_FOCUSED: The item has the focus.
1342 - @c wxLIST_STATE_SELECTED: The item is selected.
1343 - @c wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1344 - @c wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1345 - @c wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1346 - A mask indicating which state flags are valid; this is a bitlist of the
1347 flags reported above for the item state. See SetStateMask() and GetStateMask().
1348 - A mask indicating which fields of this class are valid; see SetMask() and GetMask().
1349 This is a bitlist of the following flags:
1350 - @c wxLIST_MASK_STATE: The state field is valid.
1351 - @c wxLIST_MASK_TEXT: The label field is valid.
1352 - @c wxLIST_MASK_IMAGE: The image field is valid.
1353 - @c wxLIST_MASK_DATA: The application-defined data field is valid.
1354 - @c wxLIST_MASK_WIDTH: The column width field is valid.
1355 - @c wxLIST_MASK_FORMAT: The column format field is valid.
1357 The wxListItem object can also contain item-specific colour and font
1358 information: for this you need to call one of SetTextColour(), SetBackgroundColour()
1359 or SetFont() functions on it passing it the colour/font to use.
1360 If the colour/font is not specified, the default list control colour/font is used.
1367 class wxListItem
: public wxObject
1376 Resets the item state to the default.
1381 Returns the alignment for this item.
1382 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or @c wxLIST_FORMAT_CENTRE.
1384 wxListColumnFormat
GetAlign() const;
1387 Returns the background colour for this item.
1389 wxColour
GetBackgroundColour() const;
1392 Returns the zero-based column; meaningful only in report mode.
1394 int GetColumn() const;
1397 Returns client data associated with the control.
1398 Please note that client data is associated with the item and not with subitems.
1400 wxUIntPtr
GetData() const;
1403 Returns the font used to display the item.
1405 wxFont
GetFont() const;
1408 Returns the zero-based item position.
1413 Returns the zero-based index of the image associated with the item into
1416 int GetImage() const;
1419 Returns a bit mask indicating which fields of the structure are valid.
1421 Can be any combination of the following values:
1422 - wxLIST_MASK_STATE: @b GetState is valid.
1423 - wxLIST_MASK_TEXT: @b GetText is valid.
1424 - wxLIST_MASK_IMAGE: @b GetImage is valid.
1425 - wxLIST_MASK_DATA: @b GetData is valid.
1426 - wxLIST_MASK_WIDTH: @b GetWidth is valid.
1427 - wxLIST_MASK_FORMAT: @b GetFormat is valid.
1429 long GetMask() const;
1432 Returns a bit field representing the state of the item.
1434 Can be any combination of:
1435 - wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1436 - wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1437 - wxLIST_STATE_FOCUSED: The item has the focus.
1438 - wxLIST_STATE_SELECTED: The item is selected.
1439 - wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1441 long GetState() const;
1444 Returns the label/header text.
1446 const wxString
& GetText() const;
1449 Returns the text colour.
1451 wxColour
GetTextColour() const;
1454 Meaningful only for column headers in report mode. Returns the column width.
1456 int GetWidth() const;
1459 Sets the alignment for the item. See also GetAlign()
1461 void SetAlign(wxListColumnFormat align
);
1464 Sets the background colour for the item.
1466 void SetBackgroundColour(const wxColour
& colBack
);
1469 Sets the zero-based column. Meaningful only in report mode.
1471 void SetColumn(int col
);
1475 Sets client data for the item.
1476 Please note that client data is associated with the item and not with subitems.
1478 void SetData(long data
);
1479 void SetData(void* data
);
1483 Sets the font for the item.
1485 void SetFont(const wxFont
& font
);
1488 Sets the zero-based item position.
1490 void SetId(long id
);
1493 Sets the zero-based index of the image associated with the item
1494 into the image list.
1496 void SetImage(int image
);
1499 Sets the mask of valid fields. See GetMask().
1501 void SetMask(long mask
);
1504 Sets the item state flags (note that the valid state flags are influenced
1505 by the value of the state mask, see wxListItem::SetStateMask).
1507 See GetState() for valid flag values.
1509 void SetState(long state
);
1512 Sets the bitmask that is used to determine which of the state flags
1513 are to be set. See also SetState().
1515 void SetStateMask(long stateMask
);
1518 Sets the text label for the item.
1520 void SetText(const wxString
& text
);
1523 Sets the text colour for the item.
1525 void SetTextColour(const wxColour
& colText
);
1528 Meaningful only for column headers in report mode. Sets the column width.
1530 void SetWidth(int width
);