1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxListCtrl docs
8 %% Copyright: (c) wxWidgets
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxListCtrl
}}\label{wxlistctrl
}
14 A list control presents lists in a number of formats: list view,
report view,
15 icon view and small icon view. In any case, elements are numbered from zero.
16 For all these modes, the items are stored in the control and must be added to
17 it using
\helpref{InsertItem
}{wxlistctrlinsertitem
} method.
19 A special case of
report view quite different from the other modes of the list
20 control is a virtual control in which the items data (including text, images
21 and attributes) is managed by the main program and is requested by the control
22 itself only when needed which allows to have controls with millions of items
23 without consuming much memory. To use virtual list control you must use
24 \helpref{SetItemCount
}{wxlistctrlsetitemcount
} first and overload at least
25 \helpref{OnGetItemText
}{wxlistctrlongetitemtext
} (and optionally
26 \helpref{OnGetItemImage
}{wxlistctrlongetitemimage
} or
\helpref{OnGetItemColumnImage
}{wxlistctrlongetitemcolumnimage
} and
27 \helpref{OnGetItemAttr
}{wxlistctrlongetitemattr
}) to return the information
28 about the items when the control requests it. Virtual list control can be used
29 as a normal one except that no operations which can take time proportional to
30 the number of items in the control happen -- this is required to allow having a
31 practically infinite number of items. For example, in a multiple selection
32 virtual list control, the selections won't be sent when many items are selected
33 at once because this could mean iterating over all the items.
35 Using many of wxListCtrl features is shown in the
36 \helpref{corresponding sample
}{samplelistctrl
}.
38 To intercept events from a list control, use the event table macros described
39 in
\helpref{wxListEvent
}{wxlistevent
}.
41 \wxheading{Derived from
}
43 \helpref{wxControl
}{wxcontrol
}\\
44 \helpref{wxWindow
}{wxwindow
}\\
45 \helpref{wxEvtHandler
}{wxevthandler
}\\
46 \helpref{wxObject
}{wxobject
}
48 \wxheading{Include files
}
52 \wxheading{Window styles
}
55 \begin{twocollist
}\itemsep=
0pt
56 \twocolitem{\windowstyle{wxLC
\_LIST}}{Multicolumn list view, with optional small icons.
57 Columns are computed automatically, i.e. you don't set columns as in wxLC
\_REPORT. In other words,
58 the list wraps, unlike a wxListBox.
}
59 \twocolitem{\windowstyle{wxLC
\_REPORT}}{Single or multicolumn
report view, with optional header.
}
60 \twocolitem{\windowstyle{wxLC
\_VIRTUAL}}{The application provides items text on demand. May only be used with wxLC
\_REPORT.
}
61 \twocolitem{\windowstyle{wxLC
\_ICON}}{Large icon view, with optional labels.
}
62 \twocolitem{\windowstyle{wxLC
\_SMALL\_ICON}}{Small icon view, with optional labels.
}
63 \twocolitem{\windowstyle{wxLC
\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only.
}
64 \twocolitem{\windowstyle{wxLC
\_ALIGN\_LEFT}}{Icons align to the left.
}
65 \twocolitem{\windowstyle{wxLC
\_AUTOARRANGE}}{Icons arrange themselves. Win32 only.
}
66 \twocolitem{\windowstyle{wxLC
\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.
}
67 \twocolitem{\windowstyle{wxLC
\_NO\_HEADER}}{No header in
report mode.
}
68 \twocolitem{\windowstyle{wxLC
\_SINGLE\_SEL}}{Single selection (default is multiple).
}
69 \twocolitem{\windowstyle{wxLC
\_SORT\_ASCENDING}}{Sort in ascending order (must still supply a comparison callback in SortItems.
}
70 \twocolitem{\windowstyle{wxLC
\_SORT\_DESCENDING}}{Sort in descending order (must still supply a comparison callback in SortItems.
}
71 \twocolitem{\windowstyle{wxLC
\_HRULES}}{Draws light horizontal rules between rows in
report mode.
}
72 \twocolitem{\windowstyle{wxLC
\_VRULES}}{Draws light vertical rules between columns in
report mode.
}
75 See also
\helpref{window styles overview
}{windowstyles
}.
77 \wxheading{Event handling
}
79 To process input from a list control, use these event handler macros to direct input to member
80 functions that take a
\helpref{wxListEvent
}{wxlistevent
} argument.
83 \begin{twocollist
}\itemsep=
0pt
84 \twocolitem{{\bf EVT
\_LIST\_BEGIN\_DRAG(id, func)
}}{Begin dragging with the left mouse button.
}
85 \twocolitem{{\bf EVT
\_LIST\_BEGIN\_RDRAG(id, func)
}}{Begin dragging with the right mouse button.
}
86 \twocolitem{{\bf EVT
\_LIST\_BEGIN\_LABEL\_EDIT(id, func)
}}{Begin editing a label. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
87 \twocolitem{{\bf EVT
\_LIST\_END\_LABEL\_EDIT(id, func)
}}{Finish editing a label. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
88 \twocolitem{{\bf EVT
\_LIST\_DELETE\_ITEM(id, func)
}}{Delete an item.
}
89 \twocolitem{{\bf EVT
\_LIST\_DELETE\_ALL\_ITEMS(id, func)
}}{Delete all items.
}
90 %\twocolitem{{\bf EVT\_LIST\_GET\_INFO(id, func)}}{Request information from the application, usually the item text.}
91 %\twocolitem{{\bf EVT\_LIST\_SET\_INFO(id, func)}}{Information is being supplied (not implemented).}
92 \twocolitem{{\bf EVT
\_LIST\_ITEM\_SELECTED(id, func)
}}{The item has been selected.
}
93 \twocolitem{{\bf EVT
\_LIST\_ITEM\_DESELECTED(id, func)
}}{The item has been deselected.
}
94 \twocolitem{{\bf EVT
\_LIST\_ITEM\_ACTIVATED(id, func)
}}{The item has been activated (ENTER or double click).
}
95 \twocolitem{{\bf EVT
\_LIST\_ITEM\_FOCUSED(id, func)
}}{The currently focused item has changed.
}
96 \twocolitem{{\bf EVT
\_LIST\_ITEM\_MIDDLE\_CLICK(id, func)
}}{The middle mouse button has been clicked on an item.
}
97 \twocolitem{{\bf EVT
\_LIST\_ITEM\_RIGHT\_CLICK(id, func)
}}{The right mouse button has been clicked on an item.
}
98 \twocolitem{{\bf EVT
\_LIST\_KEY\_DOWN(id, func)
}}{A key has been pressed.
}
99 \twocolitem{{\bf EVT
\_LIST\_INSERT\_ITEM(id, func)
}}{An item has been inserted.
}
100 \twocolitem{{\bf EVT
\_LIST\_COL\_CLICK(id, func)
}}{A column (
{\bf m
\_col}) has been left-clicked.
}
101 \twocolitem{{\bf EVT
\_LIST\_COL\_RIGHT\_CLICK(id, func)
}}{A column (
{\bf m
\_col}) has been right-clicked.
}
102 \twocolitem{{\bf EVT
\_LIST\_COL\_BEGIN\_DRAG(id, func)
}}{The user started resizing a column - can be vetoed.
}
103 \twocolitem{{\bf EVT
\_LIST\_COL\_DRAGGING(id, func)
}}{The divider between columns is being dragged.
}
104 \twocolitem{{\bf EVT
\_LIST\_COL\_END\_DRAG(id, func)
}}{A column has been resized by the user.
}
105 \twocolitem{{\bf EVT
\_LIST\_CACHE\_HINT(id, func)
}}{Prepare cache for a virtual list control
}
110 \helpref{wxListCtrl overview
}{wxlistctrloverview
},
\helpref{wxListView
}{wxlistview
},
\helpref{wxListBox
}{wxlistbox
},
\rtfsp
111 \helpref{wxTreeCtrl
}{wxtreectrl
},
\helpref{wxImageList
}{wximagelist
},
\helpref{wxListEvent
}{wxlistevent
},
112 \helpref{wxListItem
}{wxlistitem
}
114 \latexignore{\rtfignore{\wxheading{Members
}}}
117 \membersection{wxListCtrl::wxListCtrl
}\label{wxlistctrlctor
}
119 \func{}{wxListCtrl
}{\void}
123 \func{}{wxListCtrl
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
124 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
125 \param{long
}{ style = wxLC
\_ICON},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = wxListCtrlNameStr
}}
127 Constructor, creating and showing a list control.
129 \wxheading{Parameters
}
131 \docparam{parent
}{Parent window. Must not be NULL.
}
133 \docparam{id
}{Window identifier. A value of -
1 indicates a default value.
}
135 \docparam{pos
}{Window position.
}
137 \docparam{size
}{Window size. If the default size (-
1, -
1) is specified then the window is sized
140 \docparam{style
}{Window style. See
\helpref{wxListCtrl
}{wxlistctrl
}.
}
142 \docparam{validator
}{Window validator.
}
144 \docparam{name
}{Window name.
}
148 \helpref{wxListCtrl::Create
}{wxlistctrlcreate
},
\helpref{wxValidator
}{wxvalidator
}
151 \membersection{wxListCtrl::
\destruct{wxListCtrl
}}\label{wxlistctrldtor
}
153 \func{void
}{\destruct{wxListCtrl
}}{\void}
155 Destructor, destroying the list control.
158 \membersection{wxListCtrl::Arrange
}\label{wxlistctrlarrange
}
160 \func{bool
}{Arrange
}{\param{int
}{flag = wxLIST
\_ALIGN\_DEFAULT}}
162 Arranges the items in icon or small icon view. This only has effect on Win32.
{\it flag
} is one of:
165 \begin{twocollist
}\itemsep=
0pt
166 \twocolitem{wxLIST
\_ALIGN\_DEFAULT}{Default alignment.
}
167 \twocolitem{wxLIST
\_ALIGN\_LEFT}{Align to the left side of the control.
}
168 \twocolitem{wxLIST
\_ALIGN\_TOP}{Align to the top side of the control.
}
169 \twocolitem{wxLIST
\_ALIGN\_SNAP\_TO\_GRID}{Snap to grid.
}
173 \membersection{wxListCtrl::AssignImageList
}\label{wxlistctrlassignimagelist
}
175 \func{void
}{AssignImageList
}{\param{wxImageList*
}{ imageList
},
\param{int
}{which
}}
177 Sets the image list associated with the control and
178 takes ownership of it (i.e. the control will, unlike when using
179 SetImageList, delete the list when destroyed).
{\it which
} is one of
180 wxIMAGE
\_LIST\_NORMAL, wxIMAGE
\_LIST\_SMALL, wxIMAGE
\_LIST\_STATE (the last is unimplemented).
184 \helpref{wxListCtrl::SetImageList
}{wxlistctrlsetimagelist
}
187 \membersection{wxListCtrl::ClearAll
}\label{wxlistctrlclearall
}
189 \func{void
}{ClearAll
}{}
191 Deletes all items and all columns.
194 \membersection{wxListCtrl::Create
}\label{wxlistctrlcreate
}
196 \func{bool
}{Create
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
197 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
198 \param{long
}{ style = wxLC
\_ICON},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = wxListCtrlNameStr
}}
200 Creates the list control. See
\helpref{wxListCtrl::wxListCtrl
}{wxlistctrlctor
} for further details.
203 \membersection{wxListCtrl::DeleteAllItems
}\label{wxlistctrldeleteallitems
}
205 \func{bool
}{DeleteAllItems
}{}
207 Deletes all items in the list control.
209 {\bf NB:
} This function does
{\it not
} send the
210 {\tt wxEVT
\_COMMAND\_LIST\_DELETE\_ITEM} event because deleting many items
211 from the control would be too slow then (unlike
\helpref{DeleteItem
}{wxlistctrldeleteitem
}).
214 \membersection{wxListCtrl::DeleteColumn
}\label{wxlistctrldeletecolumn
}
216 \func{bool
}{DeleteColumn
}{\param{int
}{col
}}
221 \membersection{wxListCtrl::DeleteItem
}\label{wxlistctrldeleteitem
}
223 \func{bool
}{DeleteItem
}{\param{long
}{item
}}
225 Deletes the specified item. This function sends the
226 {\tt wxEVT
\_COMMAND\_LIST\_DELETE\_ITEM} event for the item being deleted.
228 See also:
\helpref{DeleteAllItems
}{wxlistctrldeleteallitems
}
231 \membersection{wxListCtrl::EditLabel
}\label{wxlistctrledit
}
233 \func{void
}{EditLabel
}{\param{long
}{item
}}
235 Starts editing the label of the given item. This function generates a
236 EVT
\_LIST\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
237 text control will appear for in-place editing.
239 If the user changed the label (i.e. s/he does not press ESC or leave
240 the text control without changes, a EVT
\_LIST\_END\_LABEL\_EDIT event
241 will be sent which can be vetoed as well.
244 \membersection{wxListCtrl::EnsureVisible
}\label{wxlistctrlensurevisible
}
246 \func{bool
}{EnsureVisible
}{\param{long
}{item
}}
248 Ensures this item is visible.
251 \membersection{wxListCtrl::FindItem
}\label{wxlistctrlfinditem
}
253 \func{long
}{FindItem
}{\param{long
}{start
},
\param{const wxString\&
}{str
},
\param{const bool
}{partial = false
}}
255 Find an item whose label matches this string, starting from
{\it start
} or
256 the beginning if
{\it start
} is -
1. The string comparison is case
257 insensitive. If
{\it partial
} is true then this method will look for
258 items which begin with
{\it str
}.
260 \func{long
}{FindItem
}{\param{long
}{start
},
\param{long
}{data
}}
262 Find an item whose data matches this data, starting from
{\it start
} or
263 the beginning if 'start' is -
1.
265 \func{long
}{FindItem
}{\param{long
}{start
},
\param{const wxPoint\&
}{pt
},
\param{int
}{direction
}}
267 Find an item nearest this position in the specified direction, starting from
268 {\it start
} or the beginning if
{\it start
} is -
1.
270 \pythonnote{In place of a single overloaded method name, wxPython
271 implements the following methods:
\par
272 \indented{2cm
}{\begin{twocollist
}
273 \twocolitem{{\bf FindItem(start, str, partial=false)
}}{}
274 \twocolitem{{\bf FindItemData(start, data)
}}{}
275 \twocolitem{{\bf FindItemAtPos(start, point, direction)
}}{}
279 \perlnote{In wxPerl there are three methods instead of a single overloaded
281 \indented{2cm
}{\begin{twocollist
}
282 \twocolitem{{\bf FindItem( start, str, partial = false )
}}{}
283 \twocolitem{{\bf FindItemData( start, data )
}}{}
284 \twocolitem{{\bf FindItemAtPos( start, point, direction )
}}{}
289 \membersection{wxListCtrl::GetColumn
}\label{wxlistctrlgetcolumn
}
291 \constfunc{bool
}{GetColumn
}{\param{int
}{col
},
\param{wxListItem\&
}{item
}}
293 Gets information about this column. See
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
} for more
296 \perlnote{In wxPerl this method takes only the
{\bf col
} parameter and
297 returns a Wx::ListItem ( or undef ).
}
300 \membersection{wxListCtrl::GetColumnCount
}\label{wxlistctrlgetcolumncount
}
302 \constfunc{int
}{GetColumnCount
}{\void}
304 Returns the number of columns.
307 \membersection{wxListCtrl::GetColumnWidth
}\label{wxlistctrlgetcolumnwidth
}
309 \constfunc{int
}{GetColumnWidth
}{\param{int
}{col
}}
311 Gets the column width (
report view only).
314 \membersection{wxListCtrl::GetCountPerPage
}\label{wxlistctrlgetcountperpage
}
316 \constfunc{int
}{GetCountPerPage
}{\void}
318 Gets the number of items that can fit vertically in the
319 visible area of the list control (list or
report view)
320 or the total number of items in the list control (icon
324 \membersection{wxListCtrl::GetEditControl
}\label{wxlistctrlgeteditcontrol
}
326 \constfunc{wxTextCtrl *
}{GetEditControl
}{\void}
328 Returns the edit control being currently used to edit a label. Returns
{\tt NULL
}
329 if no label is being edited.
331 {\bf NB:
} It is currently only implemented for wxMSW.
334 \membersection{wxListCtrl::GetImageList
}\label{wxlistctrlgetimagelist
}
336 \constfunc{wxImageList*
}{GetImageList
}{\param{int
}{which
}}
338 Returns the specified image list.
{\it which
} may be one of:
341 \begin{twocollist
}\itemsep=
0pt
342 \twocolitem{\windowstyle{wxIMAGE
\_LIST\_NORMAL}}{The normal (large icon) image list.
}
343 \twocolitem{\windowstyle{wxIMAGE
\_LIST\_SMALL}}{The small icon image list.
}
344 \twocolitem{\windowstyle{wxIMAGE
\_LIST\_STATE}}{The user-defined state image list (unimplemented).
}
348 \membersection{wxListCtrl::GetItem
}\label{wxlistctrlgetitem
}
350 \constfunc{bool
}{GetItem
}{\param{wxListItem\&
}{info
}}
352 Gets information about the item. See
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
} for more
355 You must call
{\it info.SetId()
} to the ID of item you're interested in
356 before calling this method.
358 \pythonnote{The wxPython version of this method takes an integer parameter
359 for the item ID, an optional integer for the column number, and
360 returns the wxListItem object.
}
362 \perlnote{In wxPerl this method takes as parameter the
{\bf ID
} of the item
363 and ( optionally ) the column, and returns a Wx::ListItem object.
}
366 \membersection{wxListCtrl::GetItemBackgroundColour
}\label{wxlistctrlgetitembackgroundcolour
}
368 \constfunc{wxColour
}{GetItemBackgroundColour
}{\param{long
}{item
}}
370 Returns the colour for this item. If the item has no specific colour, returns
371 an invalid colour (and not the default background control of the control
376 \helpref{GetItemTextColour
}{wxlistctrlgetitemtextcolour
}
379 \membersection{wxListCtrl::GetItemCount
}\label{wxlistctrlgetitemcount
}
381 \constfunc{int
}{GetItemCount
}{\void}
383 Returns the number of items in the list control.
386 \membersection{wxListCtrl::GetItemData
}\label{wxlistctrlgetitemdata
}
388 \constfunc{long
}{GetItemData
}{\param{long
}{item
}}
390 Gets the application-defined data associated with this item.
393 \membersection{wxListCtrl::GetItemFont
}\label{wxlistctrlgetitemfont
}
395 \constfunc{wxFont
}{GetItemFont
}{\param{long
}{item
}}
397 Returns the item's font.
400 \membersection{wxListCtrl::GetItemPosition
}\label{wxlistctrlgetitemposition
}
402 \constfunc{bool
}{GetItemPosition
}{\param{long
}{item
},
\param{wxPoint\&
}{pos
}}
404 Returns the position of the item, in icon or small icon view.
406 \pythonnote{The wxPython version of this method accepts only the item
407 ID and returns the wxPoint.
}
409 \perlnote{In wxPerl this method takes only the
{\bf item
} parameter and
410 returns a Wx::Point ( or undef ).
}
413 \membersection{wxListCtrl::GetItemRect
}\label{wxlistctrlgetitemrect
}
415 \constfunc{bool
}{GetItemRect
}{\param{long
}{item
},
\param{wxRect\&
}{rect
},
\param{int
}{code = wxLIST
\_RECT\_BOUNDS}}
417 Returns the rectangle representing the item's size and position, in physical
420 {\it code
} is one of wxLIST
\_RECT\_BOUNDS, wxLIST
\_RECT\_ICON, wxLIST
\_RECT\_LABEL.
422 \pythonnote{The wxPython version of this method accepts only the item
423 ID and code and returns the wxRect.
}
425 \perlnote{In wxPerl this method takes only the
{\bf item
} parameter and
426 returns a Wx::Rect ( or undef ).
}
430 \membersection{wxListCtrl::GetSubItemRect
}\label{wxlistctrlgetsubitemrect
}
432 \constfunc{bool
}{GetSubItemRect
}{\param{long
}{item
},
\param{long
}{subItem
},
\param{wxRect\&
}{rect
},
\param{int
}{code = wxLIST
\_RECT\_BOUNDS}}
434 Returns the rectangle representing the size and position, in physical
435 coordinates, of the given subitem, i.e. the part of the row
\arg{item
} in the
436 column
\arg{subItem
}.
438 This method is only meaningfull when the wxListCtrl is in the
report mode. If
439 \arg{subItem
} parameter is equal to the special value
440 \texttt{wxLIST
\_GETSUBITEMRECT\_WHOLEITEM} the return value is the same as
441 for
\helpref{GetItemRect
}{wxlistctrlgetitemrect
}.
443 \arg{code
} can be one of
\texttt{wxLIST
\_RECT\_BOUNDS},
444 \texttt{wxLIST
\_RECT\_ICON} or
\texttt{wxLIST
\_RECT\_LABEL}.
449 \membersection{wxListCtrl::GetItemSpacing
}\label{wxlistctrlgetitemspacing
}
451 \constfunc{wxSize
}{GetItemSpacing
}{\void}
453 Retrieves the spacing between icons in pixels: horizontal spacing is returned
454 as
\texttt{x
} component of the
\helpref{wxSize
}{wxsize
} object and the vertical
455 spacing as its
\texttt{y
} component.
459 \membersection{wxListCtrl::GetItemState
}\label{wxlistctrlgetitemstate
}
461 \constfunc{int
}{GetItemState
}{\param{long
}{item
},
\param{long
}{stateMask
}}
463 Gets the item state. For a list of state flags, see
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
}.
465 The
{\bf stateMask
} indicates which state flags are of interest.
468 \membersection{wxListCtrl::GetItemText
}\label{wxlistctrlgetitemtext
}
470 \constfunc{wxString
}{GetItemText
}{\param{long
}{item
}}
472 Gets the item text for this item.
475 \membersection{wxListCtrl::GetItemTextColour
}\label{wxlistctrlgetitemtextcolour
}
477 \constfunc{wxColour
}{GetItemTextColour
}{\param{long
}{item
}}
479 Returns the colour for this item. If the item has no specific colour, returns
480 an invalid colour (and not the default foreground control of the control itself
481 as this wouldn't allow distinguishing between items having the same colour as
482 the current control foreground and items with default colour which, hence, have
483 always the same colour as the control).
486 \membersection{wxListCtrl::GetNextItem
}\label{wxlistctrlgetnextitem
}
488 \constfunc{long
}{GetNextItem
}{\param{long
}{item
},
\param{int
}{geometry = wxLIST
\_NEXT\_ALL},
\param{int
}{state = wxLIST
\_STATE\_DONTCARE}}
490 Searches for an item with the given geometry or state, starting from
491 {\it item
} but excluding the
{\it item
} itself. If
{\it item
} is -
1,
492 the first item that matches the specified flags will be returned.
494 Returns the first item with given state following
{\it item
} or -
1 if
497 This function may be used to find all selected items in the control like this:
503 item = listctrl->GetNextItem(item,
505 wxLIST_STATE_SELECTED);
509 // this item is selected - do whatever is needed with it
510 wxLogMessage("Item
%ld is selected.", item);
514 {\it geometry
} can be one of:
517 \begin{twocollist
}\itemsep=
0pt
518 \twocolitem{wxLIST
\_NEXT\_ABOVE}{Searches for an item above the specified item.
}
519 \twocolitem{wxLIST
\_NEXT\_ALL}{Searches for subsequent item by index.
}
520 \twocolitem{wxLIST
\_NEXT\_BELOW}{Searches for an item below the specified item.
}
521 \twocolitem{wxLIST
\_NEXT\_LEFT}{Searches for an item to the left of the specified item.
}
522 \twocolitem{wxLIST
\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.
}
525 {\bf NB:
} this parameter is only supported by wxMSW currently and ignored on
528 {\it state
} can be a bitlist of the following:
531 \begin{twocollist
}\itemsep=
0pt
532 \twocolitem{wxLIST
\_STATE\_DONTCARE}{Don't care what the state is.
}
533 \twocolitem{wxLIST
\_STATE\_DROPHILITED}{The item indicates it is a drop target.
}
534 \twocolitem{wxLIST
\_STATE\_FOCUSED}{The item has the focus.
}
535 \twocolitem{wxLIST
\_STATE\_SELECTED}{The item is selected.
}
536 \twocolitem{wxLIST
\_STATE\_CUT}{The item is selected as part of a cut and paste operation.
}
540 \membersection{wxListCtrl::GetSelectedItemCount
}\label{wxlistctrlgetselecteditemcount
}
542 \constfunc{int
}{GetSelectedItemCount
}{\void}
544 Returns the number of selected items in the list control.
547 \membersection{wxListCtrl::GetTextColour
}\label{wxlistctrlgettextcolour
}
549 \constfunc{wxColour
}{GetTextColour
}{\void}
551 Gets the text colour of the list control.
554 \membersection{wxListCtrl::GetTopItem
}\label{wxlistctrlgettopitem
}
556 \constfunc{long
}{GetTopItem
}{\void}
558 Gets the index of the topmost visible item when in
563 \membersection{wxListCtrl::GetViewRect
}\label{wxlistctrlgetviewrect
}
565 \constfunc{wxRect
}{GetViewRect
}{\void}
567 Returns the rectangle taken by all items in the control. In other words, if the
568 controls client size were equal to the size of this rectangle, no scrollbars
569 would be needed and no free space would be left.
571 Note that this function only works in the icon and small icon views, not in
572 list or
report views (this is a limitation of the native Win32 control).
576 \membersection{wxListCtrl::HitTest
}\label{wxlistctrlhittest
}
578 \constfunc{long
}{HitTest
}{\param{const wxPoint\&
}{point
},
\param{int\&
}{flags
},
\param{long *
}{ptrSubItem
}}
580 Determines which item (if any) is at the specified point,
581 giving details in
{\it flags
}. Returns index of the item or
{\tt wxNOT
\_FOUND}
582 if no item is at the specified point.
583 {\it flags
} will be a combination of the following flags:
586 \begin{twocollist
}\itemsep=
0pt
587 \twocolitem{wxLIST
\_HITTEST\_ABOVE}{Above the client area.
}
588 \twocolitem{wxLIST
\_HITTEST\_BELOW}{Below the client area.
}
589 \twocolitem{wxLIST
\_HITTEST\_NOWHERE}{In the client area but below the last item.
}
590 \twocolitem{wxLIST
\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.
}
591 \twocolitem{wxLIST
\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.
}
592 \twocolitem{wxLIST
\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.
}
593 \twocolitem{wxLIST
\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.
}
594 \twocolitem{wxLIST
\_HITTEST\_TOLEFT}{To the right of the client area.
}
595 \twocolitem{wxLIST
\_HITTEST\_TORIGHT}{To the left of the client area.
}
596 \twocolitem{wxLIST
\_HITTEST\_ONITEM}{Combination of wxLIST
\_HITTEST\_ONITEMICON, wxLIST
\_HITTEST\_ONITEMLABEL,
597 wxLIST
\_HITTEST\_ONITEMSTATEICON.
}
600 If
\arg{ptrSubItem
} is not
\NULL and the wxListCtrl is in the
report
601 mode the subitem (or column) number will also be provided.
602 This feature is only available in version
2.7.0 or higher and is currently only
603 implemented under wxMSW and requires at least comctl32.dll of verion
4.70 on
604 the host system or the value stored in
\arg{ptrSubItem
} will be always -
1. To
605 compile this feature into wxWidgets library you need to have access to
606 commctrl.h of version
4.70 that is provided by Microsoft.
608 \pythonnote{A tuple of values is returned in the wxPython version of
609 this method. The first value is the item id and the second is the
610 flags value mentioned above.
}
612 \perlnote{In wxPerl this method only takes the
{\bf point
} parameter
613 and returns a
2-element list
{\tt ( item, flags )
}.
}
616 \membersection{wxListCtrl::InsertColumn
}\label{wxlistctrlinsertcolumn
}
618 \func{long
}{InsertColumn
}{\param{long
}{col
},
\param{wxListItem\&
}{info
}}
620 \func{long
}{InsertColumn
}{\param{long
}{col
},
\param{const wxString\&
}{heading
},
\param{int
}{format = wxLIST
\_FORMAT\_LEFT},
\rtfsp
621 \param{int
}{width = -
1}}
623 For
report view mode (only), inserts a column. For more details, see
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
}.
625 \pythonnote{In place of a single overloaded method name, wxPython
626 implements the following methods:
\par
627 \indented{2cm
}{\begin{twocollist
}
628 \twocolitem{{\bf InsertColumn(col, heading, format=wxLIST
\_FORMAT\_LEFT,
629 width=-
1)
}}{Creates a column using a header string only.
}
630 \twocolitem{{\bf InsertColumnItem(col, item)
}}{Creates a column using a
636 \membersection{wxListCtrl::InsertItem
}\label{wxlistctrlinsertitem
}
638 \func{long
}{InsertItem
}{\param{wxListItem\&
}{info
}}
640 Inserts an item, returning the index of the new item if successful,
643 \func{long
}{InsertItem
}{\param{long
}{index
},
\param{const wxString\&
}{label
}}
645 Inserts a string item.
647 \func{long
}{InsertItem
}{\param{long
}{index
},
\param{int
}{imageIndex
}}
649 Inserts an image item.
651 \func{long
}{InsertItem
}{\param{long
}{index
},
\param{const wxString\&
}{label
},
\param{int
}{imageIndex
}}
653 Insert an image/string item.
655 \wxheading{Parameters
}
657 \docparam{info
}{wxListItem object
}
659 \docparam{index
}{Index of the new item, supplied by the application
}
661 \docparam{label
}{String label
}
663 \docparam{imageIndex
}{index into the image list associated with this control and view style
}
665 \pythonnote{In place of a single overloaded method name, wxPython
666 implements the following methods:
\par
667 \indented{2cm
}{\begin{twocollist
}\itemsep=
0pt
668 \twocolitem{{\bf InsertItem(item)
}}{Inserts an item using a wxListItem.
}
669 \twocolitem{{\bf InsertStringItem(index, label)
}}{Inserts a string item.
}
670 \twocolitem{{\bf InsertImageItem(index, imageIndex)
}}{Inserts an image item.
}
671 \twocolitem{{\bf InsertImageStringItem(index, label, imageIndex)
}}{Insert an image/string item.
}
675 \perlnote{In wxPerl there are four methods instead of a single overloaded
677 \indented{2cm
}{\begin{twocollist
}
678 \twocolitem{{\bf InsertItem( item )
}}{Inserts a Wx::ListItem
}
679 \twocolitem{{\bf InsertStringItem( index, label )
}}{Inserts a string item
}
680 \twocolitem{{\bf InsertImageItem( index, imageIndex )
}}{Inserts an image item
}
681 \twocolitem{{\bf InsertImageStringItem( index, label, imageIndex )
}}{Inserts
682 an item with a string and an image
}
687 \membersection{wxListCtrl::OnGetItemAttr
}\label{wxlistctrlongetitemattr
}
689 \constfunc{virtual wxListItemAttr *
}{OnGetItemAttr
}{\param{long
}{item
}}
691 This function may be overloaded in the derived class for a control with
692 {\tt wxLC
\_VIRTUAL} style. It should return the attribute for the
693 for the specified
{\tt item
} or
{\tt NULL
} to use the default appearance
696 wxListCtrl will not delete the pointer or keep a reference of it. You can
697 return the same wxListItemAttr pointer for every OnGetItemAttr call.
699 The base class version always returns
{\tt NULL
}.
703 \helpref{OnGetItemImage
}{wxlistctrlongetitemimage
},\\
704 \helpref{OnGetItemColumnImage
}{wxlistctrlongetitemcolumnimage
},\\
705 \helpref{OnGetItemText
}{wxlistctrlongetitemtext
}
708 \membersection{wxListCtrl::OnGetItemImage
}\label{wxlistctrlongetitemimage
}
710 \constfunc{virtual int
}{OnGetItemImage
}{\param{long
}{item
}}
712 This function must be overloaded in the derived class for a control with
713 {\tt wxLC
\_VIRTUAL} style having an
\helpref{image list
}{wxlistctrlsetimagelist
}
714 (if the control doesn't have an image list, it is not necessary to overload
715 it). It should return the index of the items image in the controls image list
716 or $-
1$ for no image.
717 In a control with
{\tt wxLC
\_REPORT} style, OnGetItemImage only gets called for
718 the first column of each line.
720 The base class version always returns $-
1$.
724 \helpref{OnGetItemText
}{wxlistctrlongetitemtext
},\\
725 \helpref{OnGetItemColumnImage
}{wxlistctrlongetitemcolumnimage
},\\
726 \helpref{OnGetItemAttr
}{wxlistctrlongetitemattr
}
728 \membersection{wxListCtrl::OnGetItemColumnImage
}\label{wxlistctrlongetitemcolumnimage
}
730 \constfunc{virtual int
}{OnGetItemColumnImage
}{\param{long
}{item
},
\param{long
}{column
}}
732 Overload this function in the derived class for a control with
733 {\tt wxLC
\_VIRTUAL} and
{\tt wxLC
\_REPORT} styles in order to specify the image
734 index for the given line and column.
736 The base class version always calls OnGetItemImage for the first column, else
741 \helpref{OnGetItemText
}{wxlistctrlongetitemtext
},\\
742 \helpref{OnGetItemImage
}{wxlistctrlongetitemimage
},\\
743 \helpref{OnGetItemAttr
}{wxlistctrlongetitemattr
}
745 \membersection{wxListCtrl::OnGetItemText
}\label{wxlistctrlongetitemtext
}
747 \constfunc{virtual wxString
}{OnGetItemText
}{\param{long
}{item
},
\param{long
}{column
}}
749 This function
{\bf must
} be overloaded in the derived class for a control with
750 {\tt wxLC
\_VIRTUAL} style. It should return the string containing the text of
751 the given
{\it column
} for the specified
{\tt item
}.
755 \helpref{SetItemCount
}{wxlistctrlsetitemcount
},\\
756 \helpref{OnGetItemImage
}{wxlistctrlongetitemimage
},\\
757 \helpref{OnGetItemColumnImage
}{wxlistctrlongetitemcolumnimage
},\\
758 \helpref{OnGetItemAttr
}{wxlistctrlongetitemattr
}
761 \membersection{wxListCtrl::RefreshItem
}\label{wxlistctrlrefreshitem
}
763 \func{void
}{RefreshItem
}{\param{long
}{item
}}
765 Redraws the given
{\it item
}. This is only useful for the virtual list controls
766 as without calling this function the displayed value of the item doesn't change
767 even when the underlying data does change.
771 \helpref{RefreshItems
}{wxlistctrlrefreshitems
}
775 \membersection{wxListCtrl::RefreshItems
}\label{wxlistctrlrefreshitems
}
777 \func{void
}{RefreshItems
}{\param{long
}{itemFrom
},
\param{long
}{itemTo
}}
779 Redraws the items between
{\it itemFrom
} and
{\it itemTo
}. The starting item
780 must be less than or equal to the ending one.
782 Just as
\helpref{RefreshItem
}{wxlistctrlrefreshitem
} this is only useful for
783 virtual list controls.
787 \membersection{wxListCtrl::ScrollList
}\label{wxlistctrlscrolllist
}
789 \func{bool
}{ScrollList
}{\param{int
}{dx
},
\param{int
}{dy
}}
791 Scrolls the list control. If in icon, small icon or
report view mode,
792 {\it dx
} specifies the number of pixels to scroll. If in list view mode,
793 {\it dx
} specifies the number of columns to scroll.
{\it dy
} always specifies
794 the number of pixels to scroll vertically.
796 {\bf NB:
} This method is currently only implemented in the Windows version.
799 \membersection{wxListCtrl::SetBackgroundColour
}\label{wxlistctrlsetbackgroundcolour
}
801 \func{void
}{SetBackgroundColour
}{\param{const wxColour\&
}{col
}}
803 Sets the background colour (GetBackgroundColour already implicit in
807 \membersection{wxListCtrl::SetColumn
}\label{wxlistctrlsetcolumn
}
809 \func{bool
}{SetColumn
}{\param{int
}{col
},
\param{wxListItem\&
}{item
}}
811 Sets information about this column. See
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
} for more
815 \membersection{wxListCtrl::SetColumnWidth
}\label{wxlistctrlsetcolumnwidth
}
817 \func{bool
}{SetColumnWidth
}{\param{int
}{col
},
\param{int
}{width
}}
819 Sets the column width.
821 {\it width
} can be a width in pixels or wxLIST
\_AUTOSIZE (-
1) or wxLIST
\_AUTOSIZE\_USEHEADER (-
2).
822 wxLIST
\_AUTOSIZE will resize the column to the length of its longest item. wxLIST
\_AUTOSIZE\_USEHEADER
823 will resize the column to the length of the header (Win32) or
80 pixels (other platforms).
825 In small or normal icon view,
{\it col
} must be -
1, and the column width is set for all columns.
828 \membersection{wxListCtrl::SetImageList
}\label{wxlistctrlsetimagelist
}
830 \func{void
}{SetImageList
}{\param{wxImageList*
}{ imageList
},
\param{int
}{which
}}
832 Sets the image list associated with the control.
{\it which
} is one of
833 wxIMAGE
\_LIST\_NORMAL, wxIMAGE
\_LIST\_SMALL, wxIMAGE
\_LIST\_STATE (the last is unimplemented).
835 This method does not take ownership of the image list, you have to
840 \helpref{wxListCtrl::AssignImageList
}{wxlistctrlassignimagelist
}
844 \membersection{wxListCtrl::SetItem
}\label{wxlistctrlsetitem
}
846 \func{bool
}{SetItem
}{\param{wxListItem\&
}{info
}}
848 \func{long
}{SetItem
}{\param{long
}{index
},
\param{int
}{col
},
\param{const
}{wxString\& label
},
\param{int
}{imageId = -
1}}
850 Sets information about the item.
852 wxListItem is a class with the following members:
855 \begin{twocollist
}\itemsep=
0pt
856 \twocolitem{long m
\_mask}{Indicates which fields are valid. See the list of valid mask flags below.
}
857 \twocolitem{long m
\_itemId}{The zero-based item position.
}
858 \twocolitem{int m
\_col}{Zero-based column, if in
report mode.
}
859 \twocolitem{long m
\_state}{The state of the item. See the list of valid state flags below.
}
860 \twocolitem{long m
\_stateMask}{A mask indicating which state flags are valid. See the list of valid state flags below.
}
861 \twocolitem{wxString m
\_text}{The label/header text.
}
862 \twocolitem{int m
\_image}{The zero-based index into an image list.
}
863 \twocolitem{long m
\_data}{Application-defined data.
}
864 \twocolitem{int m
\_format}{For columns only: the format. Can be wxLIST
\_FORMAT\_LEFT, wxLIST
\_FORMAT\_RIGHT or
865 wxLIST
\_FORMAT\_CENTRE.
}
866 \twocolitem{int m
\_width}{For columns only: the column width.
}
869 The
{\bf m
\_mask} member contains a bitlist specifying which of the other fields are valid. The flags are:
872 \begin{twocollist
}\itemsep=
0pt
873 \twocolitem{wxLIST
\_MASK\_STATE}{The
{\bf m
\_state} field is valid.
}
874 \twocolitem{wxLIST
\_MASK\_TEXT}{The
{\bf m
\_text} field is valid.
}
875 \twocolitem{wxLIST
\_MASK\_IMAGE}{The
{\bf m
\_image} field is valid.
}
876 \twocolitem{wxLIST
\_MASK\_DATA}{The
{\bf m
\_data} field is valid.
}
877 \twocolitem{wxLIST
\_MASK\_WIDTH}{The
{\bf m
\_width} field is valid.
}
878 \twocolitem{wxLIST
\_MASK\_FORMAT}{The
{\bf m
\_format} field is valid.
}
881 The
{\bf m
\_stateMask} and
{\bf m
\_state} members take flags from the following:
884 \begin{twocollist
}\itemsep=
0pt
885 \twocolitem{wxLIST
\_STATE\_DONTCARE}{Don't care what the state is. Win32 only.
}
886 \twocolitem{wxLIST
\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event. Win32 only.
}
887 \twocolitem{wxLIST
\_STATE\_FOCUSED}{The item has the focus.
}
888 \twocolitem{wxLIST
\_STATE\_SELECTED}{The item is selected.
}
889 \twocolitem{wxLIST
\_STATE\_CUT}{The item is in the cut state. Win32 only.
}
892 The wxListItem object can also contain item-specific colour and font
893 information: for this you need to call one of SetTextColour(),
894 SetBackgroundColour() or SetFont() functions on it passing it the colour/font
895 to use. If the colour/font is not specified, the default list control
898 \func{long
}{SetItem
}{\param{long
}{index
},
\param{int
}{col
},
\param{const wxString\&
}{label
},
\param{int
}{imageId = -
1}}
900 Sets a string field at a particular column.
902 \pythonnote{In place of a single overloaded method name, wxPython
903 implements the following methods:
\par
904 \indented{2cm
}{\begin{twocollist
}
905 \twocolitem{{\bf SetItem(item)
}}{Sets information about the given wxListItem.
}
906 \twocolitem{{\bf SetStringItem(index, col, label, imageId)
}}{Sets a
907 string or image at a given location.
}
911 \membersection{wxListCtrl::SetItemBackgroundColour
}\label{wxlistctrlsetitembackgroundcolour
}
913 \func{void
}{SetItemBackgroundColour
}{\param{long
}{item
},
\param{const wxColour\&
}{col
}}
915 Sets the background colour for this item. This function only works in
report view.
917 The colour can be retrieved using
918 \helpref{GetItemBackgroundColour
}{wxlistctrlgetitembackgroundcolour
}.
922 \membersection{wxListCtrl::SetItemCount
}\label{wxlistctrlsetitemcount
}
924 \func{void
}{SetItemCount
}{\param{long
}{count
}}
926 This method can only be used with virtual list controls. It is used to indicate
927 to the control the number of items it contains. After calling it, the main
928 program should be ready to handle calls to various item callbacks (such as
929 \helpref{OnGetItemText
}{wxlistctrlongetitemtext
}) for all items in the range
930 from $
0$ to
{\it count
}.
933 \membersection{wxListCtrl::SetItemData
}\label{wxlistctrlsetitemdata
}
935 \func{bool
}{SetItemData
}{\param{long
}{item
},
\param{long
}{data
}}
937 Associates application-defined data with this item.
940 \membersection{wxListCtrl::SetItemFont
}\label{wxlistctrlsetitemfont
}
942 \func{void
}{SetItemFont
}{\param{long
}{item
},
\param{const wxFont\&
}{font
}}
944 Sets the item's font.
947 \membersection{wxListCtrl::SetItemImage
}\label{wxlistctrlsetitemimage
}
949 \func{bool
}{SetItemImage
}{\param{long
}{item
},
\param{int
}{image
}}
951 Sets the image associated with the item. The image is an index into the
952 image list associated with the list control. In
report view, this only sets
953 the image for the first column.
955 \func{bool
}{SetItemImage
}{\param{long
}{item
},
\param{int
}{image
},
\param{int
}{selImage
}}
957 Sets the unselected and selected images associated with the item. The images are indices into the
958 image list associated with the list control. This form is deprecated:
{\it selImage
} is not
962 \membersection{wxListCtrl::SetItemColumnImage
}\label{wxlistctrlsetitemcolumnimage
}
964 \func{bool
}{SetItemImage
}{\param{long
}{item
},
\param{long
}{column
}\param{int
}{image
}}
966 Sets the image associated with the item. In
report view, you can specify the column.
967 The image is an index into the image list associated with the list control.
970 \membersection{wxListCtrl::SetItemPosition
}\label{wxlistctrlsetitemposition
}
972 \func{bool
}{SetItemPosition
}{\param{long
}{item
},
\param{const wxPoint\&
}{pos
}}
974 Sets the position of the item, in icon or small icon view. Windows only.
977 \membersection{wxListCtrl::SetItemState
}\label{wxlistctrlsetitemstate
}
979 \func{bool
}{SetItemState
}{\param{long
}{item
},
\param{long
}{state
},
\param{long
}{stateMask
}}
981 Sets the item state. For a list of state flags, see
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
}.
983 The
{\bf stateMask
} indicates which state flags are valid.
986 \membersection{wxListCtrl::SetItemText
}\label{wxlistctrlsetitemtext
}
988 \func{void
}{SetItemText
}{\param{long
}{item
},
\param{const wxString\&
}{text
}}
990 Sets the item text for this item.
993 \membersection{wxListCtrl::SetItemTextColour
}\label{wxlistctrlsetitemtextcolour
}
995 \func{void
}{SetItemTextColour
}{\param{long
}{item
},
\param{const wxColour\&
}{col
}}
997 Sets the colour for this item. This function only works in
report view.
999 The colour can be retrieved using
1000 \helpref{GetItemTextColour
}{wxlistctrlgetitemtextcolour
}.
1003 \membersection{wxListCtrl::SetSingleStyle
}\label{wxlistctrlsetsinglestyle
}
1005 \func{void
}{SetSingleStyle
}{\param{long
}{style
},
\param{const bool
}{add = true
}}
1007 Adds or removes a single window style.
1010 \membersection{wxListCtrl::SetTextColour
}\label{wxlistctrlsettextcolour
}
1012 \func{void
}{SetTextColour
}{\param{const wxColour\&
}{col
}}
1014 Sets the text colour of the list control.
1017 \membersection{wxListCtrl::SetWindowStyleFlag
}\label{wxlistctrlsetwindowstyleflag
}
1019 \func{void
}{SetWindowStyleFlag
}{\param{long
}{style
}}
1021 Sets the whole window style, deleting all items.
1023 \membersection{wxListCtrl::SortItems
}\label{wxlistctrlsortitems
}
1025 \func{bool
}{SortItems
}{\param{wxListCtrlCompare
}{fnSortCallBack
},
\param{long
}{data
}}
1027 Call this function to sort the items in the list control. Sorting is done
1028 using the specified
{\it fnSortCallBack
} function. This function must have the
1029 following prototype:
1032 int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
1035 It is called each time when the two items must be compared and should return
0
1036 if the items are equal, negative value if the first item is less than the
1037 second one and positive value if the first one is greater than the second one
1038 (the same convention as used by
{\tt qsort(
3)
}).
1040 \wxheading{Parameters
}
1042 \docparam{item1
}{client data associated with the first item (
{\bf NOT
} the index).
}
1044 \docparam{item2
}{client data associated with the second item (
{\bf NOT
} the index).
}
1046 \docparam{data
}{the value passed to SortItems() itself.
}
1048 Notice that the control may only be sorted on client data associated with the
1049 items, so you
{\bf must
} use
\helpref{SetItemData
}{wxlistctrlsetitemdata
} if
1050 you want to be able to sort the items in the control.
1052 Please see the
\helpref{listctrl sample
}{samplelistctrl
} for an example of
1053 using this function.
1055 \pythonnote{wxPython uses the sortData parameter to pass the Python
1056 function to call, so it is not available for programmer use. Call
1057 SortItems with a reference to a callable object that expects two
1060 \perlnote{In wxPerl the comparison function must take just two parameters;
1061 however, you may use a closure to achieve an effect similar to the
1062 SortItems third parameter.
}