1
/////////////////////////////////////////////////////////////////////////////
3
// Purpose: interface of wxListCtrl
4
// Author: wxWidgets team
5
// RCS-ID: $Id: listctrl.h 71029 2012-03-27 17:28:56Z RD $
6
// Licence: wxWindows licence
7
/////////////////////////////////////////////////////////////////////////////
10
#define wxLC_VRULES 0x0001
11
#define wxLC_HRULES 0x0002
13
#define wxLC_ICON 0x0004
14
#define wxLC_SMALL_ICON 0x0008
15
#define wxLC_LIST 0x0010
16
#define wxLC_REPORT 0x0020
18
#define wxLC_ALIGN_TOP 0x0040
19
#define wxLC_ALIGN_LEFT 0x0080
20
#define wxLC_AUTOARRANGE 0x0100
21
#define wxLC_VIRTUAL 0x0200
22
#define wxLC_EDIT_LABELS 0x0400
23
#define wxLC_NO_HEADER 0x0800
24
#define wxLC_NO_SORT_HEADER 0x1000
25
#define wxLC_SINGLE_SEL 0x2000
26
#define wxLC_SORT_ASCENDING 0x4000
27
#define wxLC_SORT_DESCENDING 0x8000
29
#define wxLC_MASK_TYPE (wxLC_ICON | wxLC_SMALL_ICON | wxLC_LIST | wxLC_REPORT)
30
#define wxLC_MASK_ALIGN (wxLC_ALIGN_TOP | wxLC_ALIGN_LEFT)
31
#define wxLC_MASK_SORT (wxLC_SORT_ASCENDING | wxLC_SORT_DESCENDING)
34
/// Mask flags to tell app/GUI what fields of wxListItem are valid
35
#define wxLIST_MASK_STATE 0x0001
36
#define wxLIST_MASK_TEXT 0x0002
37
#define wxLIST_MASK_IMAGE 0x0004
38
#define wxLIST_MASK_DATA 0x0008
39
#define wxLIST_SET_ITEM 0x0010
40
#define wxLIST_MASK_WIDTH 0x0020
41
#define wxLIST_MASK_FORMAT 0x0040
43
/// State flags for indicating the state of an item
44
#define wxLIST_STATE_DONTCARE 0x0000
45
#define wxLIST_STATE_DROPHILITED 0x0001 // MSW only
46
#define wxLIST_STATE_FOCUSED 0x0002
47
#define wxLIST_STATE_SELECTED 0x0004
48
#define wxLIST_STATE_CUT 0x0008 // MSW only
49
#define wxLIST_STATE_DISABLED 0x0010 // OS2 only
50
#define wxLIST_STATE_FILTERED 0x0020 // OS2 only
51
#define wxLIST_STATE_INUSE 0x0040 // OS2 only
52
#define wxLIST_STATE_PICKED 0x0080 // OS2 only
53
#define wxLIST_STATE_SOURCE 0x0100 // OS2 only
55
/// Hit test flags, used in HitTest
56
#define wxLIST_HITTEST_ABOVE 0x0001 // Above the client area.
57
#define wxLIST_HITTEST_BELOW 0x0002 // Below the client area.
58
#define wxLIST_HITTEST_NOWHERE 0x0004 // In the client area but below the last item.
59
#define wxLIST_HITTEST_ONITEMICON 0x0020 // On the bitmap associated with an item.
60
#define wxLIST_HITTEST_ONITEMLABEL 0x0080 // On the label (string) associated with an item.
61
#define wxLIST_HITTEST_ONITEMRIGHT 0x0100 // In the area to the right of an item.
62
#define wxLIST_HITTEST_ONITEMSTATEICON 0x0200 // On the state icon for a tree view item that is in a user-defined state.
63
#define wxLIST_HITTEST_TOLEFT 0x0400 // To the left of the client area.
64
#define wxLIST_HITTEST_TORIGHT 0x0800 // To the right of the client area.
66
#define wxLIST_HITTEST_ONITEM (wxLIST_HITTEST_ONITEMICON | wxLIST_HITTEST_ONITEMLABEL | wxLIST_HITTEST_ONITEMSTATEICON)
68
/// GetSubItemRect constants
69
#define wxLIST_GETSUBITEMRECT_WHOLEITEM -1l
71
/// Flags for GetNextItem (MSW only except wxLIST_NEXT_ALL)
74
wxLIST_NEXT_ABOVE, // Searches for an item above the specified item
75
wxLIST_NEXT_ALL, // Searches for subsequent item by index
76
wxLIST_NEXT_BELOW, // Searches for an item below the specified item
77
wxLIST_NEXT_LEFT, // Searches for an item to the left of the specified item
78
wxLIST_NEXT_RIGHT // Searches for an item to the right of the specified item
81
/// Alignment flags for Arrange (MSW only except wxLIST_ALIGN_LEFT)
87
wxLIST_ALIGN_SNAP_TO_GRID
90
/// Column format (MSW only except wxLIST_FORMAT_LEFT)
91
enum wxListColumnFormat
96
wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE
99
/// Autosize values for SetColumnWidth
102
wxLIST_AUTOSIZE = -1,
103
wxLIST_AUTOSIZE_USEHEADER = -2 // partly supported by generic version
106
/// Flag values for GetItemRect
114
/// Flag values for FindItem (MSW only)
129
A list control presents lists in a number of formats: list view, report view,
130
icon view and small icon view. In any case, elements are numbered from zero.
131
For all these modes, the items are stored in the control and must be added to
132
it using wxListCtrl::InsertItem method.
134
A special case of report view quite different from the other modes of the list
135
control is a virtual control in which the items data (including text, images
136
and attributes) is managed by the main program and is requested by the control
137
itself only when needed which allows to have controls with millions of items
138
without consuming much memory. To use virtual list control you must use
139
wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText
140
(and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
141
wxListCtrl::OnGetItemAttr) to return the information about the items when the
144
Virtual list control can be used as a normal one except that no operations
145
which can take time proportional to the number of items in the control happen
146
-- this is required to allow having a practically infinite number of items.
147
For example, in a multiple selection virtual list control, the selections won't
148
be sent when many items are selected at once because this could mean iterating
151
Using many of wxListCtrl features is shown in the
152
@ref page_samples_listctrl "corresponding sample".
154
To intercept events from a list control, use the event table macros described
157
<b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native
158
implementation for report mode, and uses a generic implementation for other
159
modes. You can use the generic implementation for report mode as well by setting
160
the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1.
165
Multicolumn list view, with optional small icons. Columns are
166
computed automatically, i.e. you don't set columns as in
167
@c wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
169
Single or multicolumn report view, with optional header.
171
The application provides items text on demand. May only be used
174
Large icon view, with optional labels.
175
@style{wxLC_SMALL_ICON}
176
Small icon view, with optional labels.
177
@style{wxLC_ALIGN_TOP}
178
Icons align to the top. Win32 default, Win32 only.
179
@style{wxLC_ALIGN_LEFT}
180
Icons align to the left.
181
@style{wxLC_AUTOARRANGE}
182
Icons arrange themselves. Win32 only.
183
@style{wxLC_EDIT_LABELS}
184
Labels are editable: the application will be notified when editing
186
@style{wxLC_NO_HEADER}
187
No header in report mode.
188
@style{wxLC_SINGLE_SEL}
189
Single selection (default is multiple).
190
@style{wxLC_SORT_ASCENDING}
191
Sort in ascending order. (You must still supply a comparison callback
192
in wxListCtrl::SortItems.)
193
@style{wxLC_SORT_DESCENDING}
194
Sort in descending order. (You must still supply a comparison callback
195
in wxListCtrl::SortItems.)
197
Draws light horizontal rules between rows in report mode.
199
Draws light vertical rules between columns in report mode.
203
@beginEventEmissionTable{wxListEvent}
204
@event{EVT_LIST_BEGIN_DRAG(id, func)}
205
Begin dragging with the left mouse button.
206
Processes a @c wxEVT_COMMAND_LIST_BEGIN_DRAG event type.
207
@event{EVT_LIST_BEGIN_RDRAG(id, func)}
208
Begin dragging with the right mouse button.
209
Processes a @c wxEVT_COMMAND_LIST_BEGIN_RDRAG event type.
210
@event{EVT_BEGIN_LABEL_EDIT(id, func)}
211
Begin editing a label. This can be prevented by calling Veto().
212
Processes a @c wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT event type.
213
@event{EVT_LIST_END_LABEL_EDIT(id, func)}
214
Finish editing a label. This can be prevented by calling Veto().
215
Processes a @c wxEVT_COMMAND_LIST_END_LABEL_EDIT event type.
216
@event{EVT_LIST_DELETE_ITEM(id, func)}
218
Processes a @c wxEVT_COMMAND_LIST_DELETE_ITEM event type.
219
@event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
220
All items were deleted.
221
Processes a @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event type.
222
@event{EVT_LIST_ITEM_SELECTED(id, func)}
223
The item has been selected.
224
Processes a @c wxEVT_COMMAND_LIST_ITEM_SELECTED event type.
225
@event{EVT_LIST_ITEM_DESELECTED(id, func)}
226
The item has been deselected.
227
Processes a @c wxEVT_COMMAND_LIST_ITEM_DESELECTED event type.
228
@event{EVT_LIST_ITEM_ACTIVATED(id, func)}
229
The item has been activated (ENTER or double click).
230
Processes a @c wxEVT_COMMAND_LIST_ITEM_ACTIVATED event type.
231
@event{EVT_LIST_ITEM_FOCUSED(id, func)}
232
The currently focused item has changed.
233
Processes a @c wxEVT_COMMAND_LIST_ITEM_FOCUSED event type.
234
@event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
235
The middle mouse button has been clicked on an item. This is
236
only supported by the generic control.
237
Processes a @c wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK event type.
238
@event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
239
The right mouse button has been clicked on an item.
240
Processes a @c wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK event type.
241
@event{EVT_LIST_KEY_DOWN(id, func)}
242
A key has been pressed.
243
Processes a @c wxEVT_COMMAND_LIST_KEY_DOWN event type.
244
@event{EVT_LIST_INSERT_ITEM(id, func)}
245
An item has been inserted.
246
Processes a @c wxEVT_COMMAND_LIST_INSERT_ITEM event type.
247
@event{EVT_LIST_COL_CLICK(id, func)}
248
A column (m_col) has been left-clicked.
249
Processes a @c wxEVT_COMMAND_LIST_COL_CLICK event type.
250
@event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
251
A column (m_col) has been right-clicked.
252
Processes a @c wxEVT_COMMAND_LIST_COL_RIGHT_CLICK event type.
253
@event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
254
The user started resizing a column - can be vetoed.
255
Processes a @c wxEVT_COMMAND_LIST_COL_BEGIN_DRAG event type.
256
@event{EVT_LIST_COL_DRAGGING(id, func)}
257
The divider between columns is being dragged.
258
Processes a @c wxEVT_COMMAND_LIST_COL_DRAGGING event type.
259
@event{EVT_LIST_COL_END_DRAG(id, func)}
260
A column has been resized by the user.
261
Processes a @c wxEVT_COMMAND_LIST_COL_END_DRAG event type.
262
@event{EVT_LIST_CACHE_HINT(id, func)}
263
Prepare cache for a virtual list control.
264
Processes a @c wxEVT_COMMAND_LIST_CACHE_HINT event type.
270
@appearance{listctrl.png}
272
@see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList,
273
wxListEvent, wxListItem, wxEditableListBox
275
class wxListCtrl : public wxControl
284
Constructor, creating and showing a list control.
287
Parent window. Must not be @NULL.
289
Window identifier. The value wxID_ANY indicates a default value.
292
If ::wxDefaultPosition is specified then a default position is chosen.
295
If ::wxDefaultSize is specified then the window is sized appropriately.
297
Window style. See wxListCtrl.
303
@see Create(), wxValidator
305
wxListCtrl(wxWindow* parent, wxWindowID id,
306
const wxPoint& pos = wxDefaultPosition,
307
const wxSize& size = wxDefaultSize,
308
long style = wxLC_ICON,
309
const wxValidator& validator = wxDefaultValidator,
310
const wxString& name = wxListCtrlNameStr);
313
Destructor, destroying the list control.
315
virtual ~wxListCtrl();
318
Adds a new column to the list control in report view mode.
320
This is just a convenient wrapper for InsertColumn() which adds the new
321
column after all the existing ones without having to specify its
326
long AppendColumn(const wxString& heading,
327
int format = wxLIST_FORMAT_LEFT,
331
Arranges the items in icon or small icon view.
332
This only has effect on Win32. @a flag is one of:
333
- wxLIST_ALIGN_DEFAULT: Default alignment.
334
- wxLIST_ALIGN_LEFT: Align to the left side of the control.
335
- wxLIST_ALIGN_TOP: Align to the top side of the control.
336
- wxLIST_ALIGN_SNAP_TO_GRID: Snap to grid.
338
bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
341
Sets the image list associated with the control and takes ownership of it
342
(i.e. the control will, unlike when using SetImageList(), delete the list
343
when destroyed). @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
344
@c wxIMAGE_LIST_STATE (the last is unimplemented).
348
void AssignImageList(wxImageList* imageList, int which);
351
Deletes all items and all columns.
353
@note This sends an event of type @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS
359
Creates the list control. See wxListCtrl() for further details.
361
bool Create(wxWindow* parent, wxWindowID id,
362
const wxPoint& pos = wxDefaultPosition,
363
const wxSize& size = wxDefaultSize,
364
long style = wxLC_ICON,
365
const wxValidator& validator = wxDefaultValidator,
366
const wxString& name = wxListCtrlNameStr);
369
Deletes all items in the list control.
371
This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM
372
event because deleting many items from the control would be too slow
373
then (unlike wxListCtrl::DeleteItem) but it does send the special @c
374
wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event if the control was not empty.
375
If it was already empty, nothing is done and no event is sent.
377
@return @true if the items were successfully deleted or if the control
378
was already empty, @false if an error occurred while deleting the
381
bool DeleteAllItems();
386
bool DeleteColumn(int col);
389
Deletes the specified item.
390
This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the
393
@see DeleteAllItems()
395
bool DeleteItem(long item);
398
Starts editing the label of the given item.
400
This function generates a @c EVT_LIST_BEGIN_LABEL_EDIT event which can be
401
vetoed so that no text control will appear for in-place editing.
403
If the user changed the label (i.e. s/he does not press ESC or leave
404
the text control without changes, a @c EVT_LIST_END_LABEL_EDIT event
405
will be sent which can be vetoed as well.
407
wxTextCtrl* EditLabel(long item,
408
wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl));
411
Finish editing the label.
413
This method allows to programmatically end editing a list control item
414
in place. Usually it will only be called when editing is in progress,
415
i.e. if GetEditControl() returns non-NULL. In particular, do not call
416
it from EVT_LIST_BEGIN_LABEL_EDIT handler as the edit control is not
417
yet fully created by then, just veto the event in this handler instead
418
to prevent the editing from even starting.
420
Notice that calling this method will result in EVT_LIST_END_LABEL_EDIT
421
event being generated.
423
Currently only implemented in wxMSW.
425
@param cancel If @true, discard the changes made by user, as if @c
426
Escape key was pressed. Otherwise, accept the changes as if @c
428
@return @true if item editing wad finished or @false if no item as
431
bool EndEditLabel(bool cancel);
434
Ensures this item is visible.
436
bool EnsureVisible(long item);
439
Find an item whose label matches this string, starting from start or the
440
beginning if start is @c -1. The string comparison is case insensitive.
442
If @a partial is @true then this method will look for items which begin with @a str.
444
@return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
446
long FindItem(long start, const wxString& str,
447
bool partial = false);
450
Find an item whose data matches this data, starting from start or the
451
beginning if 'start' is @c -1.
454
In wxPerl this method is implemented as FindItemData(start, data).
457
@return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
459
long FindItem(long start, wxUIntPtr data);
462
Find an item nearest this position in the specified direction,
463
starting from @a start or the beginning if @a start is -1.
466
In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
469
@return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
471
long FindItem(long start, const wxPoint& pt, int direction);
474
Gets information about this column.
475
See SetItem() for more information.
478
In wxPerl this method takes only the @a col parameter and
479
returns a @c Wx::ListItem (or @c undef).
482
bool GetColumn(int col, wxListItem& item) const;
485
Returns the number of columns.
487
int GetColumnCount() const;
490
Gets the column index from its position in visual order.
492
After calling SetColumnsOrder(), the index returned by this function
493
corresponds to the value of the element number @a pos in the array
494
returned by GetColumnsOrder().
496
Please see SetColumnsOrder() documentation for an example and
497
additional remarks about the columns ordering.
499
@see GetColumnOrder()
501
int GetColumnIndexFromOrder(int pos) const;
504
Gets the column visual order position.
506
This function returns the index of the column which appears at the
507
given visual position, e.g. calling it with @a col equal to 0 returns
508
the index of the first shown column.
510
Please see SetColumnsOrder() documentation for an example and
511
additional remarks about the columns ordering.
513
@see GetColumnsOrder(), GetColumnIndexFromOrder()
515
int GetColumnOrder(int col) const;
518
Gets the column width (report view only).
520
int GetColumnWidth(int col) const;
523
Returns the array containing the orders of all columns.
525
On error, an empty array is returned.
527
Please see SetColumnsOrder() documentation for an example and
528
additional remarks about the columns ordering.
530
@see GetColumnOrder(), GetColumnIndexFromOrder()
532
wxArrayInt GetColumnsOrder() const;
535
Gets the number of items that can fit vertically in the visible area of
536
the list control (list or report view) or the total number of items in
537
the list control (icon or small icon view).
539
int GetCountPerPage() const;
542
Returns the edit control being currently used to edit a label.
543
Returns @NULL if no label is being edited.
545
@note It is currently only implemented for wxMSW and the generic version,
546
not for the native Mac OS X version.
548
wxTextCtrl* GetEditControl() const;
551
Returns the specified image list. @a which may be one of:
552
- wxIMAGE_LIST_NORMAL: The normal (large icon) image list.
553
- wxIMAGE_LIST_SMALL: The small icon image list.
554
- wxIMAGE_LIST_STATE: The user-defined state image list (unimplemented).
556
wxImageList* GetImageList(int which) const;
559
Gets information about the item. See SetItem() for more information.
561
You must call @e info.SetId() to set the ID of item you're interested in
562
before calling this method, and @e info.SetMask() with the flags indicating
563
what fields you need to retrieve from @a info.
566
In wxPerl this method takes as parameter the ID of the item
567
and (optionally) the column, and returns a Wx::ListItem object.
570
bool GetItem(wxListItem& info) const;
573
Returns the colour for this item.
574
If the item has no specific colour, returns an invalid colour
575
(and not the default background control of the control itself).
577
@see GetItemTextColour()
579
wxColour GetItemBackgroundColour(long item) const;
582
Returns the number of items in the list control.
584
int GetItemCount() const;
587
Gets the application-defined data associated with this item.
589
wxUIntPtr GetItemData(long item) const;
592
Returns the item's font.
594
wxFont GetItemFont(long item) const;
597
Returns the position of the item, in icon or small icon view.
600
In wxPerl this method takes only the @a item parameter and
601
returns a @c Wx::Point (or @c undef).
604
bool GetItemPosition(long item, wxPoint& pos) const;
607
Returns the rectangle representing the item's size and position, in physical
610
@a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
613
In wxPerl this method takes only the @a item and @a code parameters and
614
returns a @c Wx::Rect (or @c undef).
617
bool GetItemRect(long item, wxRect& rect,
618
int code = wxLIST_RECT_BOUNDS) const;
621
Retrieves the spacing between icons in pixels: horizontal spacing is
622
returned as @c x component of the wxSize object and the vertical spacing
623
as its @c y component.
625
wxSize GetItemSpacing() const;
628
Gets the item state. For a list of state flags, see SetItem().
629
The @a stateMask indicates which state flags are of interest.
631
int GetItemState(long item, long stateMask) const;
634
Gets the item text for this item.
637
Item (zero-based) index.
639
Item column (zero-based) index. Column 0 is the default. This
640
parameter is new in wxWidgets 2.9.1.
642
wxString GetItemText(long item, int col = 0) const;
645
Returns the colour for this item.
647
If the item has no specific colour, returns an invalid colour (and not the
648
default foreground control of the control itself as this wouldn't allow
649
distinguishing between items having the same colour as the current control
650
foreground and items with default colour which, hence, have always the
651
same colour as the control).
653
wxColour GetItemTextColour(long item) const;
656
Searches for an item with the given geometry or state, starting from
657
@a item but excluding the @a item itself.
659
If @a item is -1, the first item that matches the specified flags will be returned.
660
Returns the first item with given state following @a item or -1 if no such item found.
661
This function may be used to find all selected items in the control like this:
667
item = listctrl->GetNextItem(item,
669
wxLIST_STATE_SELECTED);
673
// this item is selected - do whatever is needed with it
674
wxLogMessage("Item %ld is selected.", item);
678
@a geometry can be one of:
679
- wxLIST_NEXT_ABOVE: Searches for an item above the specified item.
680
- wxLIST_NEXT_ALL: Searches for subsequent item by index.
681
- wxLIST_NEXT_BELOW: Searches for an item below the specified item.
682
- wxLIST_NEXT_LEFT: Searches for an item to the left of the specified item.
683
- wxLIST_NEXT_RIGHT: Searches for an item to the right of the specified item.
685
@note this parameter is only supported by wxMSW currently and ignored on
688
@a state can be a bitlist of the following:
689
- wxLIST_STATE_DONTCARE: Don't care what the state is.
690
- wxLIST_STATE_DROPHILITED: The item indicates it is a drop target.
691
- wxLIST_STATE_FOCUSED: The item has the focus.
692
- wxLIST_STATE_SELECTED: The item is selected.
693
- wxLIST_STATE_CUT: The item is selected as part of a cut and paste operation.
695
long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL,
696
int state = wxLIST_STATE_DONTCARE) const;
699
Returns the number of selected items in the list control.
701
int GetSelectedItemCount() const;
704
Returns the rectangle representing the size and position, in physical
705
coordinates, of the given subitem, i.e. the part of the row @a item in the
708
This method is only meaningful when the wxListCtrl is in the report mode.
709
If @a subItem parameter is equal to the special value
710
@c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
713
@a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or
714
@c wxLIST_RECT_LABEL.
718
bool GetSubItemRect(long item, long subItem, wxRect& rect,
719
int code = wxLIST_RECT_BOUNDS) const;
722
Gets the text colour of the list control.
724
wxColour GetTextColour() const;
727
Gets the index of the topmost visible item when in list or report view.
729
long GetTopItem() const;
732
Returns the rectangle taken by all items in the control. In other words, if the
733
controls client size were equal to the size of this rectangle, no scrollbars
734
would be needed and no free space would be left.
736
Note that this function only works in the icon and small icon views, not in
737
list or report views (this is a limitation of the native Win32 control).
739
wxRect GetViewRect() const;
742
Determines which item (if any) is at the specified point, giving details
743
in @a flags. Returns index of the item or @c wxNOT_FOUND if no item is at
746
@a flags will be a combination of the following flags:
747
- wxLIST_HITTEST_ABOVE: Above the client area.
748
- wxLIST_HITTEST_BELOW: Below the client area.
749
- wxLIST_HITTEST_NOWHERE: In the client area but below the last item.
750
- wxLIST_HITTEST_ONITEMICON: On the bitmap associated with an item.
751
- wxLIST_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
752
- wxLIST_HITTEST_ONITEMRIGHT: In the area to the right of an item.
753
- wxLIST_HITTEST_ONITEMSTATEICON: On the state icon for a tree view item
754
that is in a user-defined state.
755
- wxLIST_HITTEST_TOLEFT: To the right of the client area.
756
- wxLIST_HITTEST_TORIGHT: To the left of the client area.
757
- wxLIST_HITTEST_ONITEM: Combination of @c wxLIST_HITTEST_ONITEMICON,
758
@c wxLIST_HITTEST_ONITEMLABEL, @c wxLIST_HITTEST_ONITEMSTATEICON.
760
If @a ptrSubItem is not @NULL and the wxListCtrl is in the report
761
mode the subitem (or column) number will also be provided.
762
This feature is only available in version 2.7.0 or higher and is currently only
763
implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on
764
the host system or the value stored in @a ptrSubItem will be always -1.
765
To compile this feature into wxWidgets library you need to have access to
766
commctrl.h of version 4.70 that is provided by Microsoft.
769
In wxPerl this method only takes the @a point parameter
770
and returns a 2-element list (item, flags).
773
long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
776
Returns true if the control is currently using ::wxLC_REPORT style.
778
bool InReportView() const;
781
For report view mode (only), inserts a column.
783
For more details, see SetItem(). Also see InsertColumn(long, const
784
wxString&, int, int) overload for a usually more convenient
785
alternative to this method and the description of how the item width
786
is interpreted by this method.
788
long InsertColumn(long col, const wxListItem& info);
791
For report view mode (only), inserts a column.
793
Insert a new column in the list control in report view mode at the
794
given position specifying its most common attributes.
796
Notice that to set the image for the column you need to use
797
Insert(long, const wxListItem&) overload and specify ::wxLIST_MASK_IMAGE
801
The index where the column should be inserted. Valid indices are
802
from 0 up to GetColumnCount() inclusive and the latter can be used
803
to append the new column after the last existing one.
805
The string specifying the column heading.
807
The flags specifying the control heading text alignment.
809
If positive, the width of the column in pixels. Otherwise it can be
810
@c wxLIST_AUTOSIZE to choose the default size for the column or @c
811
wxLIST_AUTOSIZE_USEHEADER to fit the column width to @a heading or
812
to extend to fill all the remaining space for the last column.
813
Notice that in case of @c wxLIST_AUTOSIZE fixed width is used as
814
there are no items in this column to use for determining its best
815
size yet. If you want to fit the column to its contents, use
816
SetColumnWidth() after adding the items with values in this column.
818
The index of the inserted column or -1 if adding it failed.
820
long InsertColumn(long col, const wxString& heading,
821
int format = wxLIST_FORMAT_LEFT,
822
int width = wxLIST_AUTOSIZE);
825
Inserts an item, returning the index of the new item if successful, -1 otherwise.
830
long InsertItem(wxListItem& info);
833
Insert an string item.
836
Index of the new item, supplied by the application
841
In wxPerl this method is implemented as InsertStringItem(index, label).
844
long InsertItem(long index, const wxString& label);
847
Insert an image item.
850
Index of the new item, supplied by the application
852
Index into the image list associated with this control and view style
855
In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
858
long InsertItem(long index, int imageIndex);
861
Insert an image/string item.
864
Index of the new item, supplied by the application
868
Index into the image list associated with this control and view style
871
In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
874
long InsertItem(long index, const wxString& label,
878
Returns true if the control is currently in virtual report view.
880
bool IsVirtual() const;
883
Redraws the given @e item.
885
This is only useful for the virtual list controls as without calling this
886
function the displayed value of the item doesn't change even when the
887
underlying data does change.
891
void RefreshItem(long item);
894
Redraws the items between @a itemFrom and @e itemTo.
895
The starting item must be less than or equal to the ending one.
897
Just as RefreshItem() this is only useful for virtual list controls.
899
void RefreshItems(long itemFrom, long itemTo);
902
Scrolls the list control. If in icon, small icon or report view mode,
903
@a dx specifies the number of pixels to scroll. If in list view mode,
904
@a dx specifies the number of columns to scroll. @a dy always specifies
905
the number of pixels to scroll vertically.
907
@note This method is currently only implemented in the Windows version.
909
bool ScrollList(int dx, int dy);
912
Sets the background colour.
914
Note that the wxWindow::GetBackgroundColour() function of wxWindow base
915
class can be used to retrieve the current background colour.
917
virtual bool SetBackgroundColour(const wxColour& col);
920
Sets information about this column.
921
See SetItem() for more information.
923
bool SetColumn(int col, wxListItem& item);
926
Sets the column width.
928
@a width can be a width in pixels or @c wxLIST_AUTOSIZE (-1) or
929
@c wxLIST_AUTOSIZE_USEHEADER (-2).
931
@c wxLIST_AUTOSIZE will resize the column to the length of its longest item.
933
@c wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the
934
header (Win32) or 80 pixels (other platforms).
936
In small or normal icon view, @a col must be -1, and the column width is set
939
bool SetColumnWidth(int col, int width);
942
Changes the order in which the columns are shown.
944
By default, the columns of a list control appear on the screen in order
945
of their indices, i.e. the column 0 appears first, the column 1 next
946
and so on. However by using this function it is possible to arbitrarily
947
reorder the columns visual order and the user can also rearrange the
948
columns interactively by dragging them. In this case, the index of the
949
column is not the same as its order and the functions GetColumnOrder()
950
and GetColumnIndexFromOrder() should be used to translate between them.
951
Notice that all the other functions still work with the column indices,
952
i.e. the visual positioning of the columns on screen doesn't affect the
953
code setting or getting their values for example.
955
The @a orders array must have the same number elements as the number of
956
columns and contain each position exactly once. Its n-th element
957
contains the index of the column to be shown in n-th position, so for a
958
control with three columns passing an array with elements 2, 0 and 1
959
results in the third column being displayed first, the first one next
960
and the second one last.
964
wxListCtrl *list = new wxListCtrl(...);
965
for ( int i = 0; i < 3; i++ )
966
list->InsertColumn(i, wxString::Format("Column %d", i));
972
list->SetColumnsOrder(order);
974
// now list->GetColumnsOrder() will return order and
975
// list->GetColumnIndexFromOrder(n) will return order[n] and
976
// list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
977
// 1 and 2 respectively
980
Please notice that this function makes sense for report view only and
981
currently is only implemented in wxMSW port. To avoid explicit tests
982
for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER
983
as this will allow it to start working under the other platforms when
984
support for the column reordering is added there.
986
@see GetColumnsOrder()
988
bool SetColumnsOrder(const wxArrayInt& orders);
991
Sets the image list associated with the control.
993
@a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
994
@c wxIMAGE_LIST_STATE (the last is unimplemented).
996
This method does not take ownership of the image list, you have to
999
@see AssignImageList()
1001
void SetImageList(wxImageList* imageList, int which);
1004
Sets the data of an item.
1006
Using the wxListItem's mask and state mask, you can change only selected
1007
attributes of a wxListCtrl item.
1009
bool SetItem(wxListItem& info);
1012
Sets an item string field at a particular column.
1014
long SetItem(long index, int column, const wxString& label, int imageId = -1);
1017
Sets the background colour for this item.
1018
This function only works in report view mode.
1019
The colour can be retrieved using GetItemBackgroundColour().
1021
void SetItemBackgroundColour(long item, const wxColour& col);
1024
Sets the image associated with the item.
1025
In report view, you can specify the column.
1026
The image is an index into the image list associated with the list control.
1028
bool SetItemColumnImage(long item, long column, int image);
1031
This method can only be used with virtual list controls.
1033
It is used to indicate to the control the number of items it contains.
1034
After calling it, the main program should be ready to handle calls to
1035
various item callbacks (such as wxListCtrl::OnGetItemText) for all
1036
items in the range from 0 to @a count.
1038
Notice that the control is not necessarily redrawn after this call as
1039
it may be undesirable if an item which is not visible on the screen
1040
anyhow was added to or removed from a control displaying many items, if
1041
you do need to refresh the display you can just call Refresh() manually.
1043
void SetItemCount(long count);
1046
Associates application-defined data with this item.
1048
Notice that this function cannot be used to associate pointers with the control
1049
items, use SetItemPtrData() instead.
1051
bool SetItemData(long item, long data);
1054
Sets the item's font.
1056
void SetItemFont(long item, const wxFont& font);
1059
Sets the unselected and selected images associated with the item.
1060
The images are indices into the image list associated with the list control.
1062
bool SetItemImage(long item, int image, int selImage = -1);
1066
Sets the position of the item, in icon or small icon view. Windows only.
1068
bool SetItemPosition(long item, const wxPoint& pos);
1071
Associates application-defined data with this item.
1073
The @a data parameter may be either an integer or a pointer cast to the
1074
@c wxUIntPtr type which is guaranteed to be large enough to be able to
1075
contain all integer types and pointers.
1079
bool SetItemPtrData(long item, wxUIntPtr data);
1082
Sets the item state.
1084
The @a stateMask is a combination of @c wxLIST_STATE_XXX constants
1085
described in wxListItem documentation. For each of the bits specified
1086
in @a stateMask, the corresponding state is set or cleared depending on
1087
whether @a state argument contains the same bit or not.
1089
So to select an item you can use
1091
list->SetItemState(item, wxLIST_STATE_SELECTED, wxLIST_STATE_SELECTED);
1093
while to deselect it you should use
1095
list->SetItemState(item, 0, wxLIST_STATE_SELECTED);
1098
Consider using wxListView if possible to avoid dealing with this
1099
error-prone and confusing method.
1101
bool SetItemState(long item, long state, long stateMask);
1104
Sets the item text for this item.
1106
void SetItemText(long item, const wxString& text);
1109
Sets the colour for this item.
1110
This function only works in report view.
1111
The colour can be retrieved using GetItemTextColour().
1113
void SetItemTextColour(long item, const wxColour& col);
1116
Adds or removes a single window style.
1118
void SetSingleStyle(long style, bool add = true);
1121
Sets the text colour of the list control.
1123
void SetTextColour(const wxColour& col);
1126
Sets the whole window style, deleting all items.
1128
void SetWindowStyleFlag(long style);
1131
Call this function to sort the items in the list control. Sorting is done
1132
using the specified @a fnSortCallBack function. This function must have the
1133
following prototype:
1135
int wxCALLBACK wxListCompareFunction(wxIntPtr item1, wxIntPtr item2, wxIntPtr sortData)
1138
It is called each time when the two items must be compared and should return 0
1139
if the items are equal, negative value if the first item is less than the
1140
second one and positive value if the first one is greater than the second one
1141
(the same convention as used by @c qsort(3)).
1143
The parameter @e item1 is the client data associated with the first item (NOT the index).
1144
The parameter @e item2 is the client data associated with the second item (NOT the index).
1145
The parameter @e data is the value passed to SortItems() itself.
1147
Notice that the control may only be sorted on client data associated with
1148
the items, so you must use SetItemData if you want to be able to sort the
1149
items in the control.
1151
Please see the @ref page_samples_listctrl for an example of using this function.
1154
In wxPerl the comparison function must take just two parameters;
1155
however, you may use a closure to achieve an effect similar to the
1156
SortItems third parameter.
1159
bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);
1164
This function may be overridden in the derived class for a control with
1165
@c wxLC_VIRTUAL style. It should return the attribute for the specified
1166
@c item or @NULL to use the default appearance parameters.
1168
wxListCtrl will not delete the pointer or keep a reference of it.
1169
You can return the same wxListItemAttr pointer for every OnGetItemAttr() call.
1171
The base class version always returns @NULL.
1173
@see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
1174
OnGetItemColumnAttr()
1176
virtual wxListItemAttr* OnGetItemAttr(long item) const;
1179
This function may be overridden in the derived class for a control with
1180
@c wxLC_VIRTUAL style.
1182
It should return the attribute for the for the specified @a item and @a
1183
column or @NULL to use the default appearance parameters.
1185
The base class version returns @c OnGetItemAttr(item).
1187
@note Currently this function is only called under wxMSW, the other
1188
ports only support OnGetItemAttr()
1190
@see OnGetItemAttr(), OnGetItemText(),
1191
OnGetItemImage(), OnGetItemColumnImage(),
1193
virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
1196
Override this function in the derived class for a control with
1197
@c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
1198
index for the given line and column.
1200
The base class version always calls OnGetItemImage() for the first column, else
1203
@see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(),
1204
OnGetItemColumnAttr()
1206
virtual int OnGetItemColumnImage(long item, long column) const;
1209
This function must be overridden in the derived class for a control with
1210
@c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
1211
control doesn't have an image list, it is not necessary to override it).
1212
It should return the index of the items image in the controls image list
1215
In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
1216
the first column of each line.
1218
The base class version always returns -1.
1220
@see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
1222
virtual int OnGetItemImage(long item) const;
1225
This function @b must be overridden in the derived class for a control with
1226
@c wxLC_VIRTUAL style. It should return the string containing the text of
1227
the given @a column for the specified @c item.
1229
@see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
1231
virtual wxString OnGetItemText(long item, long column) const;
1239
A list event holds information about events associated with wxListCtrl objects.
1241
@beginEventTable{wxListEvent}
1242
@event{EVT_LIST_BEGIN_DRAG(id, func)}
1243
Begin dragging with the left mouse button.
1244
@event{EVT_LIST_BEGIN_RDRAG(id, func)}
1245
Begin dragging with the right mouse button.
1246
@event{EVT_LIST_BEGIN_LABEL_EDIT(id, func)}
1247
Begin editing a label. This can be prevented by calling Veto().
1248
@event{EVT_LIST_END_LABEL_EDIT(id, func)}
1249
Finish editing a label. This can be prevented by calling Veto().
1250
@event{EVT_LIST_DELETE_ITEM(id, func)}
1252
@event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
1254
@event{EVT_LIST_ITEM_SELECTED(id, func)}
1255
The item has been selected.
1256
@event{EVT_LIST_ITEM_DESELECTED(id, func)}
1257
The item has been deselected.
1258
@event{EVT_LIST_ITEM_ACTIVATED(id, func)}
1259
The item has been activated (ENTER or double click).
1260
@event{EVT_LIST_ITEM_FOCUSED(id, func)}
1261
The currently focused item has changed.
1262
@event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
1263
The middle mouse button has been clicked on an item.
1264
@event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
1265
The right mouse button has been clicked on an item.
1266
@event{EVT_LIST_KEY_DOWN(id, func)}
1267
A key has been pressed. GetIndex() may be -1 if no item is selected.
1268
@event{EVT_LIST_INSERT_ITEM(id, func)}
1269
An item has been inserted.
1270
@event{EVT_LIST_COL_CLICK(id, func)}
1271
A column (m_col) has been left-clicked.
1272
@event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
1273
A column (m_col) (which can be -1 if the click occurred outside any column)
1274
has been right-clicked.
1275
@event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
1276
The user started resizing a column - can be vetoed.
1277
@event{EVT_LIST_COL_DRAGGING(id, func)}
1278
The divider between columns is being dragged.
1279
@event{EVT_LIST_COL_END_DRAG(id, func)}
1280
A column has been resized by the user.
1281
@event{EVT_LIST_CACHE_HINT(id, func)}
1282
Prepare cache for a virtual list control
1291
class wxListEvent : public wxNotifyEvent
1297
wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
1300
For @c EVT_LIST_CACHE_HINT event only: return the first item which the
1301
list control advises us to cache.
1303
long GetCacheFrom() const;
1306
For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
1307
which the list control advises us to cache.
1309
long GetCacheTo() const;
1312
The column position: it is only used with @c COL events.
1314
For the column dragging events, it is the column to the left of the divider
1315
being dragged, for the column click events it may be -1 if the user clicked
1316
in the list control header outside any column.
1318
int GetColumn() const;
1323
long GetData() const;
1328
int GetImage() const;
1333
long GetIndex() const;
1336
An item object, used by some events. See also wxListCtrl::SetItem.
1338
const wxListItem& GetItem() const;
1341
Key code if the event is a keypress event.
1343
int GetKeyCode() const;
1346
The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
1348
const wxString& GetLabel() const;
1353
long GetMask() const;
1356
The position of the mouse pointer if the event is a drag event.
1358
wxPoint GetPoint() const;
1363
const wxString& GetText() const;
1366
This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and
1367
returns @true if it the label editing has been cancelled by the user
1368
(GetLabel() returns an empty string in this case but it doesn't allow the
1369
application to distinguish between really cancelling the edit and the
1370
admittedly rare case when the user wants to rename it to an empty string).
1372
bool IsEditCancelled() const;
1376
wxEventType wxEVT_COMMAND_LIST_BEGIN_DRAG;
1377
wxEventType wxEVT_COMMAND_LIST_BEGIN_RDRAG;
1378
wxEventType wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT;
1379
wxEventType wxEVT_COMMAND_LIST_END_LABEL_EDIT;
1380
wxEventType wxEVT_COMMAND_LIST_DELETE_ITEM;
1381
wxEventType wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS;
1382
wxEventType wxEVT_COMMAND_LIST_ITEM_SELECTED;
1383
wxEventType wxEVT_COMMAND_LIST_ITEM_DESELECTED;
1384
wxEventType wxEVT_COMMAND_LIST_KEY_DOWN;
1385
wxEventType wxEVT_COMMAND_LIST_INSERT_ITEM;
1386
wxEventType wxEVT_COMMAND_LIST_COL_CLICK;
1387
wxEventType wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK;
1388
wxEventType wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK;
1389
wxEventType wxEVT_COMMAND_LIST_ITEM_ACTIVATED;
1390
wxEventType wxEVT_COMMAND_LIST_CACHE_HINT;
1391
wxEventType wxEVT_COMMAND_LIST_COL_RIGHT_CLICK;
1392
wxEventType wxEVT_COMMAND_LIST_COL_BEGIN_DRAG;
1393
wxEventType wxEVT_COMMAND_LIST_COL_DRAGGING;
1394
wxEventType wxEVT_COMMAND_LIST_COL_END_DRAG;
1395
wxEventType wxEVT_COMMAND_LIST_ITEM_FOCUSED;
1399
@class wxListItemAttr
1401
Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
1406
@see @ref overview_listctrl, wxListCtrl, wxListItem
1408
class wxListItemAttr
1412
Default Constructor.
1417
Construct a wxListItemAttr with the specified foreground and
1418
background colors and font.
1420
wxListItemAttr(const wxColour& colText,
1421
const wxColour& colBack,
1422
const wxFont& font);
1425
Returns the currently set background color.
1427
const wxColour& GetBackgroundColour() const;
1430
Returns the currently set font.
1432
const wxFont& GetFont() const;
1435
Returns the currently set text color.
1437
const wxColour& GetTextColour() const;
1440
Returns @true if the currently set background color is valid.
1442
bool HasBackgroundColour() const;
1445
Returns @true if the currently set font is valid.
1447
bool HasFont() const;
1450
Returns @true if the currently set text color is valid.
1452
bool HasTextColour() const;
1455
Sets a new background color.
1457
void SetBackgroundColour(const wxColour& colour);
1462
void SetFont(const wxFont& font);
1465
Sets a new text color.
1467
void SetTextColour(const wxColour& colour);
1475
This class currently simply presents a simpler to use interface for the
1476
wxListCtrl -- it can be thought of as a @e façade for that complicated class.
1478
Using it is preferable to using wxListCtrl directly whenever possible because
1479
in the future some ports might implement wxListView but not the full set of
1480
wxListCtrl features.
1482
Other than different interface, this class is identical to wxListCtrl.
1483
In particular, it uses the same events, same window styles and so on.
1487
@appearance{listview.png}
1489
@see wxListView::SetColumnImage
1491
class wxListView : public wxListCtrl
1495
Resets the column image -- after calling this function, no image will be shown.
1498
the column to clear image for
1500
@see SetColumnImage()
1502
void ClearColumnImage(int col);
1505
Sets focus to the item with the given @a index.
1507
void Focus(long index);
1510
Returns the first selected item in a (presumably) multiple selection control.
1511
Together with GetNextSelected() it can be used to iterate over all selected
1512
items in the control.
1514
@return The first selected item, if any, -1 otherwise.
1516
long GetFirstSelected() const;
1519
Returns the currently focused item or -1 if none.
1521
@see IsSelected(), Focus()
1523
long GetFocusedItem() const;
1526
Used together with GetFirstSelected() to iterate over all selected items
1529
@return Returns the next selected item or -1 if there are no more of them.
1531
long GetNextSelected(long item) const;
1534
Returns @true if the item with the given @a index is selected,
1537
@see GetFirstSelected(), GetNextSelected()
1539
bool IsSelected(long index) const;
1542
Selects or unselects the given item.
1545
the item to select or unselect
1547
if @true (default), selects the item, otherwise unselects it
1549
@see wxListCtrl::SetItemState
1551
void Select(long n, bool on = true);
1554
Sets the column image for the specified column.
1555
To use the column images, the control must have a valid image list with
1559
the column to set image for
1561
the index of the column image in the controls image list
1563
void SetColumnImage(int col, int image);
1571
This class stores information about a wxListCtrl item or column.
1573
wxListItem is a class which contains informations about:
1574
- Zero based item position; see SetId() and GetId().
1575
- Zero based column index; see SetColumn() and GetColumn().
1576
- The label (or header for columns); see SetText() and GetText().
1577
- The zero based index into an image list; see GetImage() and SetImage().
1578
- Application defined data; see SetData() and GetData().
1579
- For columns only: the width of the column; see SetWidth() and GetWidth().
1580
- For columns only: the format of the column; one of @c wxLIST_FORMAT_LEFT,
1581
@c wxLIST_FORMAT_RIGHT, @c wxLIST_FORMAT_CENTRE. See SetAlign() and GetAlign().
1582
- The state of the item; see SetState() and GetState().
1583
This is a bitlist of the following flags:
1584
- @c wxLIST_STATE_FOCUSED: The item has the focus.
1585
- @c wxLIST_STATE_SELECTED: The item is selected.
1586
- @c wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1587
- @c wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1588
- @c wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1589
- A mask indicating which state flags are valid; this is a bitlist of the
1590
flags reported above for the item state. See SetStateMask() and GetStateMask().
1591
- A mask indicating which fields of this class are valid; see SetMask() and GetMask().
1592
This is a bitlist of the following flags:
1593
- @c wxLIST_MASK_STATE: The state field is valid.
1594
- @c wxLIST_MASK_TEXT: The label field is valid.
1595
- @c wxLIST_MASK_IMAGE: The image field is valid.
1596
- @c wxLIST_MASK_DATA: The application-defined data field is valid.
1597
- @c wxLIST_MASK_WIDTH: The column width field is valid.
1598
- @c wxLIST_MASK_FORMAT: The column format field is valid.
1600
The wxListItem object can also contain item-specific colour and font
1601
information: for this you need to call one of SetTextColour(), SetBackgroundColour()
1602
or SetFont() functions on it passing it the colour/font to use.
1603
If the colour/font is not specified, the default list control colour/font is used.
1610
class wxListItem : public wxObject
1619
Resets the item state to the default.
1624
Returns the alignment for this item.
1625
Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or @c wxLIST_FORMAT_CENTRE.
1627
wxListColumnFormat GetAlign() const;
1630
Returns the background colour for this item.
1632
wxColour GetBackgroundColour() const;
1635
Returns the zero-based column; meaningful only in report mode.
1637
int GetColumn() const;
1640
Returns client data associated with the control.
1641
Please note that client data is associated with the item and not with subitems.
1643
wxUIntPtr GetData() const;
1646
Returns the font used to display the item.
1648
wxFont GetFont() const;
1651
Returns the zero-based item position.
1656
Returns the zero-based index of the image associated with the item into
1659
int GetImage() const;
1662
Returns a bit mask indicating which fields of the structure are valid.
1664
Can be any combination of the following values:
1665
- wxLIST_MASK_STATE: @b GetState is valid.
1666
- wxLIST_MASK_TEXT: @b GetText is valid.
1667
- wxLIST_MASK_IMAGE: @b GetImage is valid.
1668
- wxLIST_MASK_DATA: @b GetData is valid.
1669
- wxLIST_MASK_WIDTH: @b GetWidth is valid.
1670
- wxLIST_MASK_FORMAT: @b GetFormat is valid.
1672
long GetMask() const;
1675
Returns a bit field representing the state of the item.
1677
Can be any combination of:
1678
- wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1679
- wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1680
- wxLIST_STATE_FOCUSED: The item has the focus.
1681
- wxLIST_STATE_SELECTED: The item is selected.
1682
- wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1684
long GetState() const;
1687
Returns the label/header text.
1689
const wxString& GetText() const;
1692
Returns the text colour.
1694
wxColour GetTextColour() const;
1697
Meaningful only for column headers in report mode. Returns the column width.
1699
int GetWidth() const;
1702
Sets the alignment for the item. See also GetAlign()
1704
void SetAlign(wxListColumnFormat align);
1707
Sets the background colour for the item.
1709
void SetBackgroundColour(const wxColour& colBack);
1712
Sets the zero-based column. Meaningful only in report mode.
1714
void SetColumn(int col);
1718
Sets client data for the item.
1719
Please note that client data is associated with the item and not with subitems.
1721
void SetData(long data);
1722
void SetData(void* data);
1726
Sets the font for the item.
1728
void SetFont(const wxFont& font);
1731
Sets the zero-based item position.
1733
void SetId(long id);
1736
Sets the zero-based index of the image associated with the item
1737
into the image list.
1739
void SetImage(int image);
1742
Sets the mask of valid fields. See GetMask().
1744
void SetMask(long mask);
1747
Sets the item state flags (note that the valid state flags are influenced
1748
by the value of the state mask, see wxListItem::SetStateMask).
1750
See GetState() for valid flag values.
1752
void SetState(long state);
1755
Sets the bitmask that is used to determine which of the state flags
1756
are to be set. See also SetState().
1758
void SetStateMask(long stateMask);
1761
Sets the text label for the item.
1763
void SetText(const wxString& text);
1766
Sets the text colour for the item.
1768
void SetTextColour(const wxColour& colText);
1771
Meaningful only for column headers in report mode. Sets the column width.
1773
void SetWidth(int width);