1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxListCtrl
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
9 #define wxLC_VRULES 0x0001
10 #define wxLC_HRULES 0x0002
12 #define wxLC_ICON 0x0004
13 #define wxLC_SMALL_ICON 0x0008
14 #define wxLC_LIST 0x0010
15 #define wxLC_REPORT 0x0020
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
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)
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
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
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.
65 #define wxLIST_HITTEST_ONITEM (wxLIST_HITTEST_ONITEMICON | wxLIST_HITTEST_ONITEMLABEL | wxLIST_HITTEST_ONITEMSTATEICON)
67 /// GetSubItemRect constants
68 #define wxLIST_GETSUBITEMRECT_WHOLEITEM -1l
70 /// Flags for GetNextItem (MSW only except wxLIST_NEXT_ALL)
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
80 /// Alignment flags for Arrange (MSW only except wxLIST_ALIGN_LEFT)
86 wxLIST_ALIGN_SNAP_TO_GRID
89 /// Column format (MSW only except wxLIST_FORMAT_LEFT)
90 enum wxListColumnFormat
95 wxLIST_FORMAT_CENTER
= wxLIST_FORMAT_CENTRE
98 /// Autosize values for SetColumnWidth
101 wxLIST_AUTOSIZE
= -1,
102 wxLIST_AUTOSIZE_USEHEADER
= -2 // partly supported by generic version
105 /// Flag values for GetItemRect
113 /// Flag values for FindItem (MSW only)
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.
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
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
150 Using many of wxListCtrl features is shown in the
151 @ref page_samples_listctrl "corresponding sample".
153 To intercept events from a list control, use the event table macros described
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.
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.
168 Single or multicolumn report view, with optional header.
170 The application provides items text on demand. May only be used
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
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.)
196 Draws light horizontal rules between rows in report mode.
198 Draws light vertical rules between columns in report mode.
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)}
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.
269 @appearance{listctrl}
271 @see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList,
272 wxListEvent, wxListItem, wxEditableListBox
274 class wxListCtrl
: public wxControl
283 Constructor, creating and showing a list control.
286 Parent window. Must not be @NULL.
288 Window identifier. The value wxID_ANY indicates a default value.
291 If ::wxDefaultPosition is specified then a default position is chosen.
294 If ::wxDefaultSize is specified then the window is sized appropriately.
296 Window style. See wxListCtrl.
302 @see Create(), wxValidator
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
);
312 Destructor, destroying the list control.
314 virtual ~wxListCtrl();
317 Adds a new column to the list control in report view mode.
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
325 long AppendColumn(const wxString
& heading
,
326 wxListColumnFormat format
= wxLIST_FORMAT_LEFT
,
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.
337 bool Arrange(int flag
= wxLIST_ALIGN_DEFAULT
);
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).
347 void AssignImageList(wxImageList
* imageList
, int which
);
350 Deletes all items and all columns.
352 @note This sends an event of type @c wxEVT_LIST_DELETE_ALL_ITEMS
358 Creates the list control. See wxListCtrl() for further details.
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
);
368 Deletes all items in the list control.
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.
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
380 bool DeleteAllItems();
385 bool DeleteColumn(int col
);
388 Deletes the specified item.
389 This function sends the @c wxEVT_LIST_DELETE_ITEM event for the
392 @see DeleteAllItems()
394 bool DeleteItem(long item
);
397 Starts editing the label of the given item.
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.
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.
406 wxTextCtrl
* EditLabel(long item
,
407 wxClassInfo
* textControlClass
= wxCLASSINFO(wxTextCtrl
));
410 Enable alternating row background colours (also called zebra striping).
412 This method can only be called for the control in virtual report mode,
413 i.e. having ::wxLC_REPORT and ::wxLC_VIRTUAL styles.
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.
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.
426 @see SetAlternateRowColour()
428 void EnableAlternateRowColours(bool enable
= true);
431 Enable or disable a beep if there is no match for the currently
432 entered text when searching for the item from keyboard.
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.
440 void EnableBellOnNoMatch(bool on
= true);
443 Finish editing the label.
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.
452 Notice that calling this method will result in EVT_LIST_END_LABEL_EDIT
453 event being generated.
455 Currently only implemented in wxMSW.
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
460 @return @true if item editing wad finished or @false if no item as
463 bool EndEditLabel(bool cancel
);
466 Ensures this item is visible.
468 bool EnsureVisible(long item
);
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.
474 If @a partial is @true then this method will look for items which begin with @a str.
476 @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
478 long FindItem(long start
, const wxString
& str
,
479 bool partial
= false);
482 Find an item whose data matches this data, starting from start or the
483 beginning if 'start' is @c -1.
486 In wxPerl this method is implemented as FindItemData(start, data).
489 @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
491 long FindItem(long start
, wxUIntPtr data
);
494 Find an item nearest this position in the specified direction,
495 starting from @a start or the beginning if @a start is -1.
498 In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
501 @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
503 long FindItem(long start
, const wxPoint
& pt
, int direction
);
506 Gets information about this column.
507 See SetItem() for more information.
510 In wxPerl this method takes only the @a col parameter and
511 returns a @c Wx::ListItem (or @c undef).
514 bool GetColumn(int col
, wxListItem
& item
) const;
517 Returns the number of columns.
519 int GetColumnCount() const;
522 Gets the column index from its position in visual order.
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().
528 Please see SetColumnsOrder() documentation for an example and
529 additional remarks about the columns ordering.
531 @see GetColumnOrder()
533 int GetColumnIndexFromOrder(int pos
) const;
536 Gets the column visual order position.
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.
542 Please see SetColumnsOrder() documentation for an example and
543 additional remarks about the columns ordering.
545 @see GetColumnsOrder(), GetColumnIndexFromOrder()
547 int GetColumnOrder(int col
) const;
550 Gets the column width (report view only).
552 int GetColumnWidth(int col
) const;
555 Returns the array containing the orders of all columns.
557 On error, an empty array is returned.
559 Please see SetColumnsOrder() documentation for an example and
560 additional remarks about the columns ordering.
562 @see GetColumnOrder(), GetColumnIndexFromOrder()
564 wxArrayInt
GetColumnsOrder() const;
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).
571 int GetCountPerPage() const;
574 Returns the edit control being currently used to edit a label.
575 Returns @NULL if no label is being edited.
577 @note It is currently only implemented for wxMSW and the generic version,
578 not for the native Mac OS X version.
580 wxTextCtrl
* GetEditControl() const;
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).
588 wxImageList
* GetImageList(int which
) const;
591 Gets information about the item. See SetItem() for more information.
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.
598 In wxPerl this method takes as parameter the ID of the item
599 and (optionally) the column, and returns a Wx::ListItem object.
602 bool GetItem(wxListItem
& info
) const;
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).
609 @see GetItemTextColour()
611 wxColour
GetItemBackgroundColour(long item
) const;
614 Returns the number of items in the list control.
616 int GetItemCount() const;
619 Gets the application-defined data associated with this item.
621 wxUIntPtr
GetItemData(long item
) const;
624 Returns the item's font.
626 wxFont
GetItemFont(long item
) const;
629 Returns the position of the item, in icon or small icon view.
632 In wxPerl this method takes only the @a item parameter and
633 returns a @c Wx::Point (or @c undef).
636 bool GetItemPosition(long item
, wxPoint
& pos
) const;
639 Returns the rectangle representing the item's size and position, in physical
642 @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
645 In wxPerl this method takes only the @a item and @a code parameters and
646 returns a @c Wx::Rect (or @c undef).
649 bool GetItemRect(long item
, wxRect
& rect
,
650 int code
= wxLIST_RECT_BOUNDS
) const;
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.
657 wxSize
GetItemSpacing() const;
660 Gets the item state. For a list of state flags, see SetItem().
661 The @a stateMask indicates which state flags are of interest.
663 int GetItemState(long item
, long stateMask
) const;
666 Gets the item text for this item.
669 Item (zero-based) index.
671 Item column (zero-based) index. Column 0 is the default. This
672 parameter is new in wxWidgets 2.9.1.
674 wxString
GetItemText(long item
, int col
= 0) const;
677 Returns the colour for this item.
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).
685 wxColour
GetItemTextColour(long item
) const;
688 Searches for an item with the given geometry or state, starting from
689 @a item but excluding the @a item itself.
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:
699 item = listctrl->GetNextItem(item,
701 wxLIST_STATE_SELECTED);
705 // this item is selected - do whatever is needed with it
706 wxLogMessage("Item %ld is selected.", item);
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.
717 @note this parameter is only supported by wxMSW currently and ignored on
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.
727 long GetNextItem(long item
, int geometry
= wxLIST_NEXT_ALL
,
728 int state
= wxLIST_STATE_DONTCARE
) const;
731 Returns the number of selected items in the list control.
733 int GetSelectedItemCount() const;
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
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
745 @a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or
746 @c wxLIST_RECT_LABEL.
750 bool GetSubItemRect(long item
, long subItem
, wxRect
& rect
,
751 int code
= wxLIST_RECT_BOUNDS
) const;
754 Gets the text colour of the list control.
756 wxColour
GetTextColour() const;
759 Gets the index of the topmost visible item when in list or report view.
761 long GetTopItem() const;
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.
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).
771 wxRect
GetViewRect() const;
774 Set the alternative row background colour to a specific colour.
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
781 As EnableAlternateRowColours(), this method can only be used with
782 controls having ::wxLC_REPORT and ::wxLC_VIRTUAL styles.
785 A valid alternative row background colour to enable alternating
786 rows or invalid colour to disable them and use the same colour for
791 void SetAlternateRowColour(const wxColour
& colour
);
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
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.
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.
821 In wxPerl this method only takes the @a point parameter
822 and returns a 2-element list (item, flags).
825 long HitTest(const wxPoint
& point
, int& flags
, long* ptrSubItem
= NULL
) const;
828 Returns true if the control is currently using ::wxLC_REPORT style.
830 bool InReportView() const;
833 For report view mode (only), inserts a column.
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.
840 long InsertColumn(long col
, const wxListItem
& info
);
843 For report view mode (only), inserts a column.
845 Insert a new column in the list control in report view mode at the
846 given position specifying its most common attributes.
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
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.
857 The string specifying the column heading.
859 The flags specifying the control heading text alignment.
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.
870 The index of the inserted column or -1 if adding it failed.
872 long InsertColumn(long col
, const wxString
& heading
,
873 int format
= wxLIST_FORMAT_LEFT
,
874 int width
= wxLIST_AUTOSIZE
);
877 Inserts an item, returning the index of the new item if successful, -1 otherwise.
882 long InsertItem(wxListItem
& info
);
885 Insert an string item.
888 Index of the new item, supplied by the application
893 In wxPerl this method is implemented as InsertStringItem(index, label).
896 long InsertItem(long index
, const wxString
& label
);
899 Insert an image item.
902 Index of the new item, supplied by the application
904 Index into the image list associated with this control and view style
907 In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
910 long InsertItem(long index
, int imageIndex
);
913 Insert an image/string item.
916 Index of the new item, supplied by the application
920 Index into the image list associated with this control and view style
923 In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
926 long InsertItem(long index
, const wxString
& label
,
930 Returns true if the control is currently in virtual report view.
932 bool IsVirtual() const;
935 Redraws the given @e item.
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.
943 void RefreshItem(long item
);
946 Redraws the items between @a itemFrom and @e itemTo.
947 The starting item must be less than or equal to the ending one.
949 Just as RefreshItem() this is only useful for virtual list controls.
951 void RefreshItems(long itemFrom
, long itemTo
);
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.
959 @note This method is currently only implemented in the Windows version.
961 bool ScrollList(int dx
, int dy
);
964 Sets the background colour.
966 Note that the wxWindow::GetBackgroundColour() function of wxWindow base
967 class can be used to retrieve the current background colour.
969 virtual bool SetBackgroundColour(const wxColour
& col
);
972 Sets information about this column.
973 See SetItem() for more information.
975 bool SetColumn(int col
, wxListItem
& item
);
978 Sets the column width.
980 @a width can be a width in pixels or @c wxLIST_AUTOSIZE (-1) or
981 @c wxLIST_AUTOSIZE_USEHEADER (-2).
983 @c wxLIST_AUTOSIZE will resize the column to the length of its longest item.
985 @c wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the
986 header (Win32) or 80 pixels (other platforms).
988 In small or normal icon view, @a col must be -1, and the column width is set
991 bool SetColumnWidth(int col
, int width
);
994 Changes the order in which the columns are shown.
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.
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.
1014 Example of using it:
1016 wxListCtrl *list = new wxListCtrl(...);
1017 for ( int i = 0; i < 3; i++ )
1018 list->InsertColumn(i, wxString::Format("Column %d", i));
1020 wxArrayInt order(3);
1024 list->SetColumnsOrder(order);
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
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.
1038 @see GetColumnsOrder()
1040 bool SetColumnsOrder(const wxArrayInt
& orders
);
1043 Sets the image list associated with the control.
1045 @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
1046 @c wxIMAGE_LIST_STATE (the last is unimplemented).
1048 This method does not take ownership of the image list, you have to
1051 @see AssignImageList()
1053 void SetImageList(wxImageList
* imageList
, int which
);
1056 Sets the data of an item.
1058 Using the wxListItem's mask and state mask, you can change only selected
1059 attributes of a wxListCtrl item.
1061 bool SetItem(wxListItem
& info
);
1064 Sets an item string field at a particular column.
1066 long SetItem(long index
, int column
, const wxString
& label
, int imageId
= -1);
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().
1073 void SetItemBackgroundColour(long item
, const wxColour
& col
);
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.
1080 bool SetItemColumnImage(long item
, long column
, int image
);
1083 This method can only be used with virtual list controls.
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.
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.
1095 void SetItemCount(long count
);
1098 Associates application-defined data with this item.
1100 Notice that this function cannot be used to associate pointers with the control
1101 items, use SetItemPtrData() instead.
1103 bool SetItemData(long item
, long data
);
1106 Sets the item's font.
1108 void SetItemFont(long item
, const wxFont
& font
);
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.
1114 bool SetItemImage(long item
, int image
, int selImage
= -1);
1118 Sets the position of the item, in icon or small icon view. Windows only.
1120 bool SetItemPosition(long item
, const wxPoint
& pos
);
1123 Associates application-defined data with this item.
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.
1131 bool SetItemPtrData(long item
, wxUIntPtr data
);
1134 Sets the item state.
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.
1141 So to select an item you can use
1143 list->SetItemState(item, wxLIST_STATE_SELECTED, wxLIST_STATE_SELECTED);
1145 while to deselect it you should use
1147 list->SetItemState(item, 0, wxLIST_STATE_SELECTED);
1150 Consider using wxListView if possible to avoid dealing with this
1151 error-prone and confusing method.
1153 bool SetItemState(long item
, long state
, long stateMask
);
1156 Sets the item text for this item.
1158 void SetItemText(long item
, const wxString
& text
);
1161 Sets the colour for this item.
1162 This function only works in report view.
1163 The colour can be retrieved using GetItemTextColour().
1165 void SetItemTextColour(long item
, const wxColour
& col
);
1168 Adds or removes a single window style.
1170 void SetSingleStyle(long style
, bool add
= true);
1173 Sets the text colour of the list control.
1175 void SetTextColour(const wxColour
& col
);
1178 Sets the whole window style, deleting all items.
1180 void SetWindowStyleFlag(long style
);
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:
1187 int wxCALLBACK wxListCompareFunction(wxIntPtr item1, wxIntPtr item2, wxIntPtr sortData)
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)).
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.
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.
1203 Please see the @ref page_samples_listctrl for an example of using this function.
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.
1211 bool SortItems(wxListCtrlCompare fnSortCallBack
, wxIntPtr data
);
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.
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.
1223 The base class version always returns @NULL.
1225 @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
1226 OnGetItemColumnAttr()
1228 virtual wxListItemAttr
* OnGetItemAttr(long item
) const;
1231 This function may be overridden in the derived class for a control with
1232 @c wxLC_VIRTUAL style.
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.
1237 The base class version returns @c OnGetItemAttr(item).
1239 @note Currently this function is only called under wxMSW, the other
1240 ports only support OnGetItemAttr()
1242 @see OnGetItemAttr(), OnGetItemText(),
1243 OnGetItemImage(), OnGetItemColumnImage(),
1245 virtual wxListItemAttr
* OnGetItemColumnAttr(long item
, long column
) const;
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.
1252 The base class version always calls OnGetItemImage() for the first column, else
1255 @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(),
1256 OnGetItemColumnAttr()
1258 virtual int OnGetItemColumnImage(long item
, long column
) const;
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
1267 In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
1268 the first column of each line.
1270 The base class version always returns -1.
1272 @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
1274 virtual int OnGetItemImage(long item
) const;
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.
1281 @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
1283 virtual wxString
OnGetItemText(long item
, long column
) const;
1291 A list event holds information about events associated with wxListCtrl objects.
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)}
1304 @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
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
1343 class wxListEvent
: public wxNotifyEvent
1349 wxListEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0);
1352 For @c EVT_LIST_CACHE_HINT event only: return the first item which the
1353 list control advises us to cache.
1355 long GetCacheFrom() const;
1358 For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
1359 which the list control advises us to cache.
1361 long GetCacheTo() const;
1364 The column position: it is only used with @c COL events.
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.
1370 int GetColumn() const;
1375 long GetData() const;
1380 int GetImage() const;
1385 long GetIndex() const;
1388 An item object, used by some events. See also wxListCtrl::SetItem.
1390 const wxListItem
& GetItem() const;
1393 Key code if the event is a keypress event.
1395 int GetKeyCode() const;
1398 The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
1400 const wxString
& GetLabel() const;
1405 long GetMask() const;
1408 The position of the mouse pointer if the event is a drag event.
1410 wxPoint
GetPoint() const;
1415 const wxString
& GetText() const;
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).
1424 bool IsEditCancelled() const;
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
;
1451 @class wxListItemAttr
1453 Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
1458 @see @ref overview_listctrl, wxListCtrl, wxListItem
1460 class wxListItemAttr
1464 Default Constructor.
1469 Construct a wxListItemAttr with the specified foreground and
1470 background colors and font.
1472 wxListItemAttr(const wxColour
& colText
,
1473 const wxColour
& colBack
,
1474 const wxFont
& font
);
1477 Returns the currently set background color.
1479 const wxColour
& GetBackgroundColour() const;
1482 Returns the currently set font.
1484 const wxFont
& GetFont() const;
1487 Returns the currently set text color.
1489 const wxColour
& GetTextColour() const;
1492 Returns @true if the currently set background color is valid.
1494 bool HasBackgroundColour() const;
1497 Returns @true if the currently set font is valid.
1499 bool HasFont() const;
1502 Returns @true if the currently set text color is valid.
1504 bool HasTextColour() const;
1507 Sets a new background color.
1509 void SetBackgroundColour(const wxColour
& colour
);
1514 void SetFont(const wxFont
& font
);
1517 Sets a new text color.
1519 void SetTextColour(const wxColour
& colour
);
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.
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.
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.
1539 @appearance{listview}
1541 @see wxListView::SetColumnImage
1543 class wxListView
: public wxListCtrl
1547 Resets the column image -- after calling this function, no image will be shown.
1550 the column to clear image for
1552 @see SetColumnImage()
1554 void ClearColumnImage(int col
);
1557 Sets focus to the item with the given @a index.
1559 void Focus(long index
);
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.
1566 @return The first selected item, if any, -1 otherwise.
1568 long GetFirstSelected() const;
1571 Returns the currently focused item or -1 if none.
1573 @see IsSelected(), Focus()
1575 long GetFocusedItem() const;
1578 Used together with GetFirstSelected() to iterate over all selected items
1581 @return Returns the next selected item or -1 if there are no more of them.
1583 long GetNextSelected(long item
) const;
1586 Returns @true if the item with the given @a index is selected,
1589 @see GetFirstSelected(), GetNextSelected()
1591 bool IsSelected(long index
) const;
1594 Selects or unselects the given item.
1597 the item to select or unselect
1599 if @true (default), selects the item, otherwise unselects it
1601 @see wxListCtrl::SetItemState
1603 void Select(long n
, bool on
= true);
1606 Sets the column image for the specified column.
1607 To use the column images, the control must have a valid image list with
1611 the column to set image for
1613 the index of the column image in the controls image list
1615 void SetColumnImage(int col
, int image
);
1623 This class stores information about a wxListCtrl item or column.
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.
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.
1662 class wxListItem
: public wxObject
1671 Resets the item state to the default.
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.
1679 wxListColumnFormat
GetAlign() const;
1682 Returns the background colour for this item.
1684 wxColour
GetBackgroundColour() const;
1687 Returns the zero-based column; meaningful only in report mode.
1689 int GetColumn() const;
1692 Returns client data associated with the control.
1693 Please note that client data is associated with the item and not with subitems.
1695 wxUIntPtr
GetData() const;
1698 Returns the font used to display the item.
1700 wxFont
GetFont() const;
1703 Returns the zero-based item position.
1708 Returns the zero-based index of the image associated with the item into
1711 int GetImage() const;
1714 Returns a bit mask indicating which fields of the structure are valid.
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.
1724 long GetMask() const;
1727 Returns a bit field representing the state of the item.
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.
1736 long GetState() const;
1739 Returns the label/header text.
1741 const wxString
& GetText() const;
1744 Returns the text colour.
1746 wxColour
GetTextColour() const;
1749 Meaningful only for column headers in report mode. Returns the column width.
1751 int GetWidth() const;
1754 Sets the alignment for the item. See also GetAlign()
1756 void SetAlign(wxListColumnFormat align
);
1759 Sets the background colour for the item.
1761 void SetBackgroundColour(const wxColour
& colBack
);
1764 Sets the zero-based column. Meaningful only in report mode.
1766 void SetColumn(int col
);
1770 Sets client data for the item.
1771 Please note that client data is associated with the item and not with subitems.
1773 void SetData(long data
);
1774 void SetData(void* data
);
1778 Sets the font for the item.
1780 void SetFont(const wxFont
& font
);
1783 Sets the zero-based item position.
1785 void SetId(long id
);
1788 Sets the zero-based index of the image associated with the item
1789 into the image list.
1791 void SetImage(int image
);
1794 Sets the mask of valid fields. See GetMask().
1796 void SetMask(long mask
);
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).
1802 See GetState() for valid flag values.
1804 void SetState(long state
);
1807 Sets the bitmask that is used to determine which of the state flags
1808 are to be set. See also SetState().
1810 void SetStateMask(long stateMask
);
1813 Sets the text label for the item.
1815 void SetText(const wxString
& text
);
1818 Sets the text colour for the item.
1820 void SetTextColour(const wxColour
& colText
);
1823 Meaningful only for column headers in report mode. Sets the column width.
1825 void SetWidth(int width
);