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 overload 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
26 Virtual list control can be used as a normal one except that no operations
27 which can take time proportional to the number of items in the control happen
28 -- this is required to allow having a practically infinite number of items.
29 For example, in a multiple selection virtual list control, the selections won't
30 be sent when many items are selected at once because this could mean iterating
33 Using many of wxListCtrl features is shown in the
34 @ref page_samples_listctrl "corresponding sample".
36 To intercept events from a list control, use the event table macros described
39 <b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native
40 implementation for report mode, and uses a generic implementation for other
41 modes. You can use the generic implementation for report mode as well by setting
42 the @c mac.listctrl.always_use_generic system option (see wxSystemOption) to 1.
44 <b>wxMSW Note</b>: In report view, the control has several columns
45 which are identified by their internal indices. By default, these indices
46 correspond to their order on screen, i.e. the column 0 appears first (in the
47 left-to-right or maybe right-to-left if the current language uses this writing
48 direction), the column 1 next and so on. However it is possible to reorder the
49 columns visual order using SetColumnsOrder() method and the user can also
50 rearrange the columns interactively by dragging them. In this case, the index
51 of the column is not the same as its order and the functions GetColumnOrder()
52 and GetColumnIndexFromOrder() should be used to translate between them.
57 Multicolumn list view, with optional small icons. Columns are
58 computed automatically, i.e. you don't set columns as in
59 wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
61 Single or multicolumn report view, with optional header.
63 The application provides items text on demand. May only be used
66 Large icon view, with optional labels.
67 @style{wxLC_SMALL_ICON}
68 Small icon view, with optional labels.
69 @style{wxLC_ALIGN_TOP}
70 Icons align to the top. Win32 default, Win32 only.
71 @style{wxLC_ALIGN_LEFT}
72 Icons align to the left.
73 @style{wxLC_AUTOARRANGE}
74 Icons arrange themselves. Win32 only.
75 @style{wxLC_EDIT_LABELS}
76 Labels are editable: the application will be notified when editing
78 @style{wxLC_NO_HEADER}
79 No header in report mode.
80 @style{wxLC_SINGLE_SEL}
81 Single selection (default is multiple).
82 @style{wxLC_SORT_ASCENDING}
83 Sort in ascending order. (You must still supply a comparison callback
84 in wxListCtrl::SortItems.)
85 @style{wxLC_SORT_DESCENDING}
86 Sort in descending order. (You must still supply a comparison callback
87 in wxListCtrl::SortItems.)
89 Draws light horizontal rules between rows in report mode.
91 Draws light vertical rules between columns in report mode.
95 @beginEventTable{wxListEvent}
96 @event{EVT_LIST_BEGIN_DRAG(id, func)}
97 Begin dragging with the left mouse button.
98 @event{EVT_LIST_BEGIN_RDRAG(id, func)}
99 Begin dragging with the right mouse button..
100 @event{EVT_BEGIN_LABEL_EDIT(id, func)}
101 Begin editing a label. This can be prevented by calling Veto().
102 @event{EVT_LIST_END_LABEL_EDIT(id, func)}
103 Finish editing a label. This can be prevented by calling Veto().
104 @event{EVT_LIST_DELETE_ITEM(id, func)}
106 @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
107 All items were deleted.
108 @event{EVT_LIST_ITEM_SELECTED(id, func)}
109 The item has been selected.
110 @event{EVT_LIST_ITEM_DESELECTED(id, func)}
111 The item has been deselected.
112 @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
113 The item has been activated (ENTER or double click).
114 @event{EVT_LIST_ITEM_FOCUSED(id, func)}
115 The currently focused item has changed.
116 @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
117 The middle mouse button has been clicked on an item.
118 @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
119 The right mouse button has been clicked on an item.
120 @event{EVT_LIST_KEY_DOWN(id, func)}
121 A key has been pressed.
122 @event{EVT_LIST_INSERT_ITEM(id, func)}
123 An item has been inserted.
124 @event{EVT_LIST_COL_CLICK(id, func)}
125 A column (m_col) has been left-clicked.
126 @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
127 A column (m_col) has been right-clicked.
128 @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
129 The user started resizing a column - can be vetoed.
130 @event{EVT_LIST_COL_DRAGGING(id, func)}
131 The divider between columns is being dragged.
132 @event{EVT_LIST_COL_END_DRAG(id, func)}
133 A column has been resized by the user.
134 @event{EVT_LIST_CACHE_HINT(id, func)}
135 Prepare cache for a virtual list control.
141 @appearance{listctrl.png}
143 @see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList,
144 wxListEvent, wxListItem, wxEditableListBox
146 class wxListCtrl
: public wxControl
155 Constructor, creating and showing a list control.
158 Parent window. Must not be @NULL.
160 Window identifier. The value wxID_ANY indicates a default value.
165 If wxDefaultSize is specified then the window is sized appropriately.
167 Window style. See wxListCtrl.
173 @see Create(), wxValidator
175 wxListCtrl(wxWindow
* parent
, wxWindowID id
,
176 const wxPoint
& pos
= wxDefaultPosition
,
177 const wxSize
& size
= wxDefaultSize
,
178 long style
= wxLC_ICON
,
179 const wxValidator
& validator
= wxDefaultValidator
,
180 const wxString
& name
= wxListCtrlNameStr
);
183 Destructor, destroying the list control.
185 virtual ~wxListCtrl();
188 Arranges the items in icon or small icon view.
189 This only has effect on Win32. @a flag is one of:
190 - wxLIST_ALIGN_DEFAULT: Default alignment.
191 - wxLIST_ALIGN_LEFT: Align to the left side of the control.
192 - wxLIST_ALIGN_TOP: Align to the top side of the control.
193 - wxLIST_ALIGN_SNAP_TO_GRID: Snap to grid.
195 bool Arrange(int flag
= wxLIST_ALIGN_DEFAULT
);
198 Sets the image list associated with the control and takes ownership of it
199 (i.e. the control will, unlike when using SetImageList(), delete the list
200 when destroyed). @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
201 @c wxIMAGE_LIST_STATE (the last is unimplemented).
205 void AssignImageList(wxImageList
* imageList
, int which
);
208 Deletes all items and all columns.
213 Creates the list control. See wxListCtrl() for further details.
215 bool Create(wxWindow
* parent
, wxWindowID id
,
216 const wxPoint
& pos
= wxDefaultPosition
,
217 const wxSize
& size
= wxDefaultSize
,
218 long style
= wxLC_ICON
,
219 const wxValidator
& validator
= wxDefaultValidator
,
220 const wxString
& name
= wxListCtrlNameStr
);
223 Deletes all items in the list control.
225 @note This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM
226 event because deleting many items from the control would be too slow
227 then (unlike wxListCtrl::DeleteItem).
229 bool DeleteAllItems();
234 bool DeleteColumn(int col
);
237 Deletes the specified item.
238 This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the
241 @see DeleteAllItems()
243 bool DeleteItem(long item
);
246 Starts editing the label of the given item.
248 This function generates a @c EVT_LIST_BEGIN_LABEL_EDIT event which can be
249 vetoed so that no text control will appear for in-place editing.
251 If the user changed the label (i.e. s/he does not press ESC or leave
252 the text control without changes, a @c EVT_LIST_END_LABEL_EDIT event
253 will be sent which can be vetoed as well.
255 wxTextCtrl
* EditLabel(long item
,
256 wxClassInfo
* textControlClass
= CLASSINFO(wxTextCtrl
));
259 Ensures this item is visible.
261 bool EnsureVisible(long item
);
264 Find an item whose label matches this string, starting from start or the
265 beginning if start is @c -1. The string comparison is case insensitive.
267 If @a partial is @true then this method will look for items which begin with @a str.
269 long FindItem(long start
, const wxString
& str
,
270 bool partial
= false);
273 Find an item whose data matches this data, starting from start or the
274 beginning if 'start' is @c -1.
276 long FindItem(long start
, long 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.
282 long FindItem(long start
, const wxPoint
& pt
, int direction
);
285 Gets information about this column.
286 See SetItem() for more information.
288 bool GetColumn(int col
, wxListItem
& item
) const;
291 Returns the number of columns.
293 int GetColumnCount() const;
296 Gets the column number by visual order index (report view only).
298 int GetColumnIndexFromOrder(int order
) const;
301 Gets the column visual order index (valid in report view only).
303 int GetColumnOrder(int col
) const;
306 Gets the column width (report view only).
308 int GetColumnWidth(int col
) const;
311 Returns the array containing the orders of all columns.
312 On error, an empty array is returned.
314 wxArrayInt
GetColumnsOrder() const;
317 Gets the number of items that can fit vertically in the visible area of
318 the list control (list or report view) or the total number of items in
319 the list control (icon or small icon view).
321 int GetCountPerPage() const;
324 Returns the edit control being currently used to edit a label.
325 Returns @NULL if no label is being edited.
327 @note It is currently only implemented for wxMSW and the generic version,
328 not for the native Mac OS X version.
330 wxTextCtrl
* GetEditControl() const;
333 Returns the specified image list. @a which may be one of:
334 - wxIMAGE_LIST_NORMAL: The normal (large icon) image list.
335 - wxIMAGE_LIST_SMALL: The small icon image list.
336 - wxIMAGE_LIST_STATE: The user-defined state image list (unimplemented).
338 wxImageList
* GetImageList(int which
) const;
341 Gets information about the item. See SetItem() for more information.
342 You must call @e info.SetId() to the ID of item you're interested in
343 before calling this method.
345 bool GetItem(wxListItem
& info
) const;
348 Returns the colour for this item.
349 If the item has no specific colour, returns an invalid colour
350 (and not the default background control of the control itself).
352 @see GetItemTextColour()
354 wxColour
GetItemBackgroundColour(long item
) const;
357 Returns the number of items in the list control.
359 int GetItemCount() const;
362 Gets the application-defined data associated with this item.
364 wxUIntPtr
GetItemData(long item
) const;
367 Returns the item's font.
369 wxFont
GetItemFont(long item
) const;
372 Returns the position of the item, in icon or small icon view.
374 bool GetItemPosition(long item
, wxPoint
& pos
) const;
377 Returns the rectangle representing the item's size and position, in physical
380 @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
382 bool GetItemRect(long item
, wxRect
& rect
,
383 int code
= wxLIST_RECT_BOUNDS
) const;
386 Retrieves the spacing between icons in pixels: horizontal spacing is
387 returned as @c x component of the wxSize object and the vertical spacing
388 as its @c y component.
390 wxSize
GetItemSpacing() const;
393 Gets the item state. For a list of state flags, see SetItem().
394 The @a stateMask indicates which state flags are of interest.
396 int GetItemState(long item
, long stateMask
) const;
399 Gets the item text for this item.
401 wxString
GetItemText(long item
) const;
404 Returns the colour for this item.
406 If the item has no specific colour, returns an invalid colour (and not the
407 default foreground control of the control itself as this wouldn't allow
408 distinguishing between items having the same colour as the current control
409 foreground and items with default colour which, hence, have always the
410 same colour as the control).
412 wxColour
GetItemTextColour(long item
) const;
415 Searches for an item with the given geometry or state, starting from
416 @a item but excluding the @a item itself.
418 If @a item is -1, the first item that matches the specified flags will be returned.
419 Returns the first item with given state following @a item or -1 if no such item found.
420 This function may be used to find all selected items in the control like this:
426 item = listctrl->GetNextItem(item,
428 wxLIST_STATE_SELECTED);
432 // this item is selected - do whatever is needed with it
433 wxLogMessage("Item %ld is selected.", item);
437 @a geometry can be one of:
438 - wxLIST_NEXT_ABOVE: Searches for an item above the specified item.
439 - wxLIST_NEXT_ALL: Searches for subsequent item by index.
440 - wxLIST_NEXT_BELOW: Searches for an item below the specified item.
441 - wxLIST_NEXT_LEFT: Searches for an item to the left of the specified item.
442 - wxLIST_NEXT_RIGHT: Searches for an item to the right of the specified item.
444 @note this parameter is only supported by wxMSW currently and ignored on
447 @a state can be a bitlist of the following:
448 - wxLIST_STATE_DONTCARE: Don't care what the state is.
449 - wxLIST_STATE_DROPHILITED: The item indicates it is a drop target.
450 - wxLIST_STATE_FOCUSED: The item has the focus.
451 - wxLIST_STATE_SELECTED: The item is selected.
452 - wxLIST_STATE_CUT: The item is selected as part of a cut and paste operation.
454 long GetNextItem(long item
, int geometry
= wxLIST_NEXT_ALL
,
455 int state
= wxLIST_STATE_DONTCARE
) const;
458 Returns the number of selected items in the list control.
460 int GetSelectedItemCount() const;
463 Returns the rectangle representing the size and position, in physical
464 coordinates, of the given subitem, i.e. the part of the row @a item in the
467 This method is only meaningfull when the wxListCtrl is in the report mode.
468 If @a subItem parameter is equal to the special value
469 @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
472 @a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or
473 @c wxLIST_RECT_LABEL.
477 bool GetSubItemRect(long item
, long subItem
, wxRect
& rect
,
478 int code
= wxLIST_RECT_BOUNDS
) const;
481 Gets the text colour of the list control.
483 wxColour
GetTextColour() const;
486 Gets the index of the topmost visible item when in list or report view.
488 long GetTopItem() const;
491 Returns the rectangle taken by all items in the control. In other words, if the
492 controls client size were equal to the size of this rectangle, no scrollbars
493 would be needed and no free space would be left.
495 Note that this function only works in the icon and small icon views, not in
496 list or report views (this is a limitation of the native Win32 control).
498 wxRect
GetViewRect() const;
501 Determines which item (if any) is at the specified point, giving details
502 in @a flags. Returns index of the item or @c wxNOT_FOUND if no item is at
505 @a flags will be a combination of the following flags:
506 - wxLIST_HITTEST_ABOVE: Above the client area.
507 - wxLIST_HITTEST_BELOW: Below the client area.
508 - wxLIST_HITTEST_NOWHERE: In the client area but below the last item.
509 - wxLIST_HITTEST_ONITEMICON: On the bitmap associated with an item.
510 - wxLIST_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
511 - wxLIST_HITTEST_ONITEMRIGHT: In the area to the right of an item.
512 - wxLIST_HITTEST_ONITEMSTATEICON: On the state icon for a tree view item
513 that is in a user-defined state.
514 - wxLIST_HITTEST_TOLEFT: To the right of the client area.
515 - wxLIST_HITTEST_TORIGHT: To the left of the client area.
516 - wxLIST_HITTEST_ONITEM: Combination of @c wxLIST_HITTEST_ONITEMICON,
517 @c wxLIST_HITTEST_ONITEMLABEL, @c wxLIST_HITTEST_ONITEMSTATEICON.
519 If @a ptrSubItem is not @NULL and the wxListCtrl is in the report
520 mode the subitem (or column) number will also be provided.
521 This feature is only available in version 2.7.0 or higher and is currently only
522 implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on
523 the host system or the value stored in @a ptrSubItem will be always -1.
524 To compile this feature into wxWidgets library you need to have access to
525 commctrl.h of version 4.70 that is provided by Microsoft.
527 long HitTest(const wxPoint
& point
, int& flags
, long* ptrSubItem
= NULL
) const;
530 For report view mode (only), inserts a column. For more details, see SetItem().
532 long InsertColumn(long col
, wxListItem
& info
);
535 For report view mode (only), inserts a column. For more details, see SetItem().
537 long InsertColumn(long col
, const wxString
& heading
,
538 int format
= wxLIST_FORMAT_LEFT
,
542 Inserts an item, returning the index of the new item if successful, -1 otherwise.
547 long InsertItem(wxListItem
& info
);
550 Insert an string item.
553 Index of the new item, supplied by the application
557 long InsertItem(long index
, const wxString
& label
);
560 Insert an image item.
563 Index of the new item, supplied by the application
565 Index into the image list associated with this control and view style
567 long InsertItem(long index
, int imageIndex
);
570 Insert an image/string item.
573 Index of the new item, supplied by the application
577 Index into the image list associated with this control and view style
579 long InsertItem(long index
, const wxString
& label
,
583 This function may be overloaded in the derived class for a control with
584 @c wxLC_VIRTUAL style. It should return the attribute for the specified
585 @c item or @NULL to use the default appearance parameters.
587 wxListCtrl will not delete the pointer or keep a reference of it.
588 You can return the same wxListItemAttr pointer for every OnGetItemAttr() call.
590 The base class version always returns @NULL.
592 @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText()
594 virtual wxListItemAttr
* OnGetItemAttr(long item
) const;
597 Overload this function in the derived class for a control with
598 @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
599 index for the given line and column.
601 The base class version always calls OnGetItemImage() for the first column, else
604 @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr()
606 virtual int OnGetItemColumnImage(long item
, long column
) const;
609 This function must be overloaded in the derived class for a control with
610 @c wxLC_VIRTUAL style having an @ref SetImageList() "image list"
611 (if the control doesn't have an image list, it is not necessary to overload it).
612 It should return the index of the items image in the controls image list
615 In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
616 the first column of each line.
618 The base class version always returns -1.
620 @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
622 virtual int OnGetItemImage(long item
) const;
625 This function @b must be overloaded in the derived class for a control with
626 @c wxLC_VIRTUAL style. It should return the string containing the text of
627 the given @a column for the specified @c item.
629 @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
631 virtual wxString
OnGetItemText(long item
, long column
) const;
634 Redraws the given @e item.
636 This is only useful for the virtual list controls as without calling this
637 function the displayed value of the item doesn't change even when the
638 underlying data does change.
642 void RefreshItem(long item
);
645 Redraws the items between @a itemFrom and @e itemTo.
646 The starting item must be less than or equal to the ending one.
648 Just as RefreshItem() this is only useful for virtual list controls.
650 void RefreshItems(long itemFrom
, long itemTo
);
653 Scrolls the list control. If in icon, small icon or report view mode,
654 @a dx specifies the number of pixels to scroll. If in list view mode,
655 @a dx specifies the number of columns to scroll. @a dy always specifies
656 the number of pixels to scroll vertically.
658 @note This method is currently only implemented in the Windows version.
660 bool ScrollList(int dx
, int dy
);
663 Sets the background colour.
665 Note that the wxWindow::GetBackgroundColour() function of wxWindow base
666 class can be used to retrieve the current background colour.
668 virtual bool SetBackgroundColour(const wxColour
& col
);
671 Sets information about this column.
672 See SetItem() for more information.
674 bool SetColumn(int col
, wxListItem
& item
);
677 Sets the column width.
679 @a width can be a width in pixels or @c wxLIST_AUTOSIZE (-1) or
680 @c wxLIST_AUTOSIZE_USEHEADER (-2).
682 @c wxLIST_AUTOSIZE will resize the column to the length of its longest item.
684 @c wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the
685 header (Win32) or 80 pixels (other platforms).
687 In small or normal icon view, @a col must be -1, and the column width is set
690 bool SetColumnWidth(int col
, int width
);
693 Sets the order of all columns at once.
695 The @a orders array must have the same number elements as the number of
696 columns and contain each position exactly once.
698 This function is valid in report view only.
700 bool SetColumnOrder(const wxArrayInt
& orders
) const;
703 Sets the image list associated with the control.
705 @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
706 @c wxIMAGE_LIST_STATE (the last is unimplemented).
708 This method does not take ownership of the image list, you have to
711 @see AssignImageList()
713 void SetImageList(wxImageList
* imageList
, int which
);
716 Sets the data of an item.
718 Using the wxListItem's mask and state mask, you can change only selected
719 attributes of a wxListCtrl item.
721 bool SetItem(wxListItem
& info
);
724 Sets an item string field at a particular column.
726 long SetItem(long index
, int column
, const wxString
& label
, int imageId
= -1);
729 Sets the background colour for this item.
730 This function only works in report view mode.
731 The colour can be retrieved using GetItemBackgroundColour().
733 void SetItemBackgroundColour(long item
, const wxColour
& col
);
736 Sets the image associated with the item.
737 In report view, you can specify the column.
738 The image is an index into the image list associated with the list control.
740 bool SetItemColumnImage(long item
, long column
, int image
);
743 This method can only be used with virtual list controls.
745 It is used to indicate to the control the number of items it contains.
746 After calling it, the main program should be ready to handle calls to
747 various item callbacks (such as wxListCtrl::OnGetItemText) for all
748 items in the range from 0 to @a count.
750 Notice that the control is not necessarily redrawn after this call as
751 it may be undesirable if an item which is not visible on the screen
752 anyhow was added to or removed from a control displaying many items, if
753 you do need to refresh the display you can just call Refresh() manually.
755 void SetItemCount(long count
);
758 Associates application-defined data with this item.
760 Notice that this function cannot be used to associate pointers with the control
761 items, use SetItemPtrData() instead.
763 bool SetItemData(long item
, long data
);
766 Sets the item's font.
768 void SetItemFont(long item
, const wxFont
& font
);
771 Sets the unselected and selected images associated with the item.
772 The images are indices into the image list associated with the list control.
774 bool SetItemImage(long item
, int image
, int selImage
= -1);
777 Sets the unselected and selected images associated with the item.
778 The images are indices into the image list associated with the list control.
781 This form is deprecated: @a selImage is not used; use the other
782 SetItemImage() overload.
784 bool SetItemImage(long item
, int image
, int selImage
= -1);
787 Sets the position of the item, in icon or small icon view. Windows only.
789 bool SetItemPosition(long item
, const wxPoint
& pos
);
792 Associates application-defined data with this item.
794 The @a data parameter may be either an integer or a pointer cast to the
795 @c wxUIntPtr type which is guaranteed to be large enough to be able to
796 contain all integer types and pointers.
800 bool SetItemPtrData(long item
, wxUIntPtr data
);
803 Sets the item state. For a list of state flags, see SetItem().
804 The @b stateMask indicates which state flags are valid.
806 bool SetItemState(long item
, long state
, long stateMask
);
809 Sets the item text for this item.
811 void SetItemText(long item
, const wxString
& text
);
814 Sets the colour for this item.
815 This function only works in report view.
816 The colour can be retrieved using GetItemTextColour().
818 void SetItemTextColour(long item
, const wxColour
& col
);
821 Adds or removes a single window style.
823 void SetSingleStyle(long style
, bool add
= true);
826 Sets the text colour of the list control.
828 void SetTextColour(const wxColour
& col
);
831 Sets the whole window style, deleting all items.
833 void SetWindowStyleFlag(long style
);
836 Call this function to sort the items in the list control. Sorting is done
837 using the specified @a fnSortCallBack function. This function must have the
840 int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
843 It is called each time when the two items must be compared and should return 0
844 if the items are equal, negative value if the first item is less than the
845 second one and positive value if the first one is greater than the second one
846 (the same convention as used by @c qsort(3)).
848 The parameter @e item1 is the client data associated with the first item (NOT the index).
849 The parameter @e item2 is the client data associated with the second item (NOT the index).
850 The parameter @e data is the value passed to SortItems() itself.
852 Notice that the control may only be sorted on client data associated with
853 the items, so you must use SetItemData if you want to be able to sort the
854 items in the control.
856 Please see the @ref page_samples_listctrl for an example of using this function.
858 bool SortItems(wxListCtrlCompare fnSortCallBack
, long data
);
866 A list event holds information about events associated with wxListCtrl objects.
868 @beginEventTable{wxListEvent}
869 @event{EVT_LIST_BEGIN_DRAG(id, func)}
870 Begin dragging with the left mouse button.
871 @event{EVT_LIST_BEGIN_RDRAG(id, func)}
872 Begin dragging with the right mouse button.
873 @event{EVT_LIST_BEGIN_LABEL_EDIT(id, func)}
874 Begin editing a label. This can be prevented by calling Veto().
875 @event{EVT_LIST_END_LABEL_EDIT(id, func)}
876 Finish editing a label. This can be prevented by calling Veto().
877 @event{EVT_LIST_DELETE_ITEM(id, func)}
879 @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
881 @event{EVT_LIST_ITEM_SELECTED(id, func)}
882 The item has been selected.
883 @event{EVT_LIST_ITEM_DESELECTED(id, func)}
884 The item has been deselected.
885 @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
886 The item has been activated (ENTER or double click).
887 @event{EVT_LIST_ITEM_FOCUSED(id, func)}
888 The currently focused item has changed.
889 @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
890 The middle mouse button has been clicked on an item.
891 @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
892 The right mouse button has been clicked on an item.
893 @event{EVT_LIST_KEY_DOWN(id, func)}
894 A key has been pressed.
895 @event{EVT_LIST_INSERT_ITEM(id, func)}
896 An item has been inserted.
897 @event{EVT_LIST_COL_CLICK(id, func)}
898 A column (m_col) has been left-clicked.
899 @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
900 A column (m_col) (which can be -1 if the click occurred outside any column)
901 has been right-clicked.
902 @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
903 The user started resizing a column - can be vetoed.
904 @event{EVT_LIST_COL_DRAGGING(id, func)}
905 The divider between columns is being dragged.
906 @event{EVT_LIST_COL_END_DRAG(id, func)}
907 A column has been resized by the user.
908 @event{EVT_LIST_CACHE_HINT(id, func)}
909 Prepare cache for a virtual list control
918 class wxListEvent
: public wxNotifyEvent
924 wxListEvent(wxEventType commandType
= 0, int id
= 0);
927 For @c EVT_LIST_CACHE_HINT event only: return the first item which the
928 list control advises us to cache.
930 long GetCacheFrom() const;
933 For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
934 which the list control advises us to cache.
936 long GetCacheTo() const;
939 The column position: it is only used with @c COL events.
941 For the column dragging events, it is the column to the left of the divider
942 being dragged, for the column click events it may be -1 if the user clicked
943 in the list control header outside any column.
945 int GetColumn() const;
950 long GetData() const;
955 int GetImage() const;
960 long GetIndex() const;
963 An item object, used by some events. See also wxListCtrl::SetItem.
965 const wxListItem
& GetItem() const;
968 Key code if the event is a keypress event.
970 int GetKeyCode() const;
973 The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
975 const wxString
& GetLabel() const;
980 long GetMask() const;
983 The position of the mouse pointer if the event is a drag event.
985 wxPoint
GetPoint() const;
990 const wxString
& GetText() const;
993 This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and
994 returns @true if it the label editing has been cancelled by the user
995 (GetLabel() returns an empty string in this case but it doesn't allow the
996 application to distinguish between really cancelling the edit and the
997 admittedly rare case when the user wants to rename it to an empty string).
999 bool IsEditCancelled() const;
1005 @class wxListItemAttr
1007 Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
1012 @see @ref overview_listctrl, wxListCtrl, wxListItem
1014 class wxListItemAttr
1018 Default Constructor.
1023 Construct a wxListItemAttr with the specified foreground and
1024 background colors and font.
1026 wxListItemAttr(const wxColour colText
,
1027 const wxColour colBack
,
1031 Returns the currently set background color.
1033 const wxColour
& GetBackgroundColour() const;
1036 Returns the currently set font.
1038 const wxFont
& GetFont() const;
1041 Returns the currently set text color.
1043 const wxColour
& GetTextColour() const;
1046 Returns @true if the currently set background color is valid.
1048 bool HasBackgroundColour() const;
1051 Returns @true if the currently set font is valid.
1053 bool HasFont() const;
1056 Returns @true if the currently set text color is valid.
1058 bool HasTextColour() const;
1061 Sets a new background color.
1063 void SetBackgroundColour(const wxColour
& colour
);
1068 void SetFont(const wxFont
& font
);
1071 Sets a new text color.
1073 void SetTextColour(const wxColour
& colour
);
1081 This class currently simply presents a simpler to use interface for the
1082 wxListCtrl -- it can be thought of as a @e façade for that complicated class.
1084 Using it is preferable to using wxListCtrl directly whenever possible because
1085 in the future some ports might implement wxListView but not the full set of
1086 wxListCtrl features.
1088 Other than different interface, this class is identical to wxListCtrl.
1089 In particular, it uses the same events, same window styles and so on.
1093 @appearance{listview.png}
1095 @see wxListView::SetColumnImage
1097 class wxListView
: public wxListCtrl
1101 Resets the column image -- after calling this function, no image will be shown.
1104 the column to clear image for
1106 @see SetColumnImage()
1108 void ClearColumnImage(int col
);
1111 Sets focus to the item with the given @a index.
1113 void Focus(long index
);
1116 Returns the first selected item in a (presumably) multiple selection control.
1117 Together with GetNextSelected() it can be used to iterate over all selected
1118 items in the control.
1120 @return The first selected item, if any, -1 otherwise.
1122 long GetFirstSelected() const;
1125 Returns the currently focused item or -1 if none.
1127 @see IsSelected(), Focus()
1129 long GetFocusedItem() const;
1132 Used together with GetFirstSelected() to iterate over all selected items
1135 @return Returns the next selected item or -1 if there are no more of them.
1137 long GetNextSelected(long item
) const;
1140 Returns @true if the item with the given @a index is selected,
1143 @see GetFirstSelected(), GetNextSelected()
1145 bool IsSelected(long index
) const;
1148 Selects or unselects the given item.
1151 the item to select or unselect
1153 if @true (default), selects the item, otherwise unselects it
1155 @see wxListCtrl::SetItemState
1157 void Select(long n
, bool on
= true);
1160 Sets the column image for the specified column.
1161 To use the column images, the control must have a valid image list with
1165 the column to set image for
1167 the index of the column image in the controls image list
1169 void SetColumnImage(int col
, int image
);
1174 Column format (MSW only except wxLIST_FORMAT_LEFT).
1176 enum wxListColumnFormat
1179 wxLIST_FORMAT_RIGHT
,
1180 wxLIST_FORMAT_CENTRE
,
1181 wxLIST_FORMAT_CENTER
= wxLIST_FORMAT_CENTRE
1187 This class stores information about a wxListCtrl item or column.
1189 wxListItem is a class which contains informations about:
1190 - Zero based item position; see SetId() and GetId().
1191 - Zero based column index; see SetColumn() and GetColumn().
1192 - The label (or header for columns); see SetText() and GetText().
1193 - The zero based index into an image list; see GetImage() and SetImage().
1194 - Application defined data; see SetData() and GetData().
1195 - For columns only: the width of the column; see SetWidth() and GetWidth().
1196 - For columns only: the format of the column; one of @c wxLIST_FORMAT_LEFT,
1197 @c wxLIST_FORMAT_RIGHT, @c wxLIST_FORMAT_CENTRE. See SetAlign() and GetAlign().
1198 - The state of the item; see SetState() and GetState().
1199 This is a bitlist of the following flags:
1200 - @c wxLIST_STATE_FOCUSED: The item has the focus.
1201 - @c wxLIST_STATE_SELECTED: The item is selected.
1202 - @c wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1203 - @c wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1204 - @c wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1205 - A mask indicating which state flags are valid; this is a bitlist of the
1206 flags reported above for the item state. See SetStateMask() and GetStateMask().
1207 - A mask indicating which fields of this class are valid; see SetMask() and GetMask().
1208 This is a bitlist of the following flags:
1209 - @c wxLIST_MASK_STATE: The state field is valid.
1210 - @c wxLIST_MASK_TEXT: The label field is valid.
1211 - @c wxLIST_MASK_IMAGE: The image field is valid.
1212 - @c wxLIST_MASK_DATA: The application-defined data field is valid.
1213 - @c wxLIST_MASK_WIDTH: The column width field is valid.
1214 - @c wxLIST_MASK_FORMAT: The column format field is valid.
1216 The wxListItem object can also contain item-specific colour and font
1217 information: for this you need to call one of SetTextColour(), SetBackgroundColour()
1218 or SetFont() functions on it passing it the colour/font to use.
1219 If the colour/font is not specified, the default list control colour/font is used.
1226 class wxListItem
: public wxObject
1235 Resets the item state to the default.
1240 Returns the alignment for this item.
1241 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or @c wxLIST_FORMAT_CENTRE.
1243 wxListColumnFormat
GetAlign() const;
1246 Returns the background colour for this item.
1248 wxColour
GetBackgroundColour() const;
1251 Returns the zero-based column; meaningful only in report mode.
1253 int GetColumn() const;
1256 Returns client data associated with the control.
1257 Please note that client data is associated with the item and not with subitems.
1259 wxUIntPtr
GetData() const;
1262 Returns the font used to display the item.
1264 wxFont
GetFont() const;
1267 Returns the zero-based item position.
1272 Returns the zero-based index of the image associated with the item into
1275 int GetImage() const;
1278 Returns a bit mask indicating which fields of the structure are valid.
1280 Can be any combination of the following values:
1281 - wxLIST_MASK_STATE: @b GetState is valid.
1282 - wxLIST_MASK_TEXT: @b GetText is valid.
1283 - wxLIST_MASK_IMAGE: @b GetImage is valid.
1284 - wxLIST_MASK_DATA: @b GetData is valid.
1285 - wxLIST_MASK_WIDTH: @b GetWidth is valid.
1286 - wxLIST_MASK_FORMAT: @b GetFormat is valid.
1288 long GetMask() const;
1291 Returns a bit field representing the state of the item.
1293 Can be any combination of:
1294 - wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1295 - wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1296 - wxLIST_STATE_FOCUSED: The item has the focus.
1297 - wxLIST_STATE_SELECTED: The item is selected.
1298 - wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1300 long GetState() const;
1303 Returns the label/header text.
1305 const wxString
& GetText() const;
1308 Returns the text colour.
1310 wxColour
GetTextColour() const;
1313 Meaningful only for column headers in report mode. Returns the column width.
1315 int GetWidth() const;
1318 Sets the alignment for the item. See also GetAlign()
1320 void SetAlign(wxListColumnFormat align
);
1323 Sets the background colour for the item.
1325 void SetBackgroundColour(const wxColour
& colBack
);
1328 Sets the zero-based column. Meaningful only in report mode.
1330 void SetColumn(int col
);
1334 Sets client data for the item.
1335 Please note that client data is associated with the item and not with subitems.
1337 void SetData(long data
);
1338 void SetData(void* data
);
1342 Sets the font for the item.
1344 void SetFont(const wxFont
& font
);
1347 Sets the zero-based item position.
1349 void SetId(long id
);
1352 Sets the zero-based index of the image associated with the item
1353 into the image list.
1355 void SetImage(int image
);
1358 Sets the mask of valid fields. See GetMask().
1360 void SetMask(long mask
);
1363 Sets the item state flags (note that the valid state flags are influenced
1364 by the value of the state mask, see wxListItem::SetStateMask).
1366 See GetState() for valid flag values.
1368 void SetState(long state
);
1371 Sets the bitmask that is used to determine which of the state flags
1372 are to be set. See also SetState().
1374 void SetStateMask(long stateMask
);
1377 Sets the text label for the item.
1379 void SetText(const wxString
& text
);
1382 Sets the text colour for the item.
1384 void SetTextColour(const wxColour
& colText
);
1387 Meaningful only for column headers in report mode. Sets the column width.
1389 void SetWidth(int width
);