1 \section{\class{wxListCtrl
}}\label{wxlistctrl
}
3 A list control presents lists in a number of formats: list view,
report view,
4 icon view and small icon view. In any case, elements are numbered from zero.
6 Using many of wxListCtrl is shown in the
7 \helpref{corresponding sample
}{samplelistctrl
}.
9 To intercept events from a list control, use the event table macros described
10 in
\helpref{wxListEvent
}{wxlistevent
}.
12 \wxheading{Derived from
}
14 \helpref{wxControl
}{wxcontrol
}\\
15 \helpref{wxWindow
}{wxwindow
}\\
16 \helpref{wxEvtHandler
}{wxevthandler
}\\
17 \helpref{wxObject
}{wxobject
}
19 \wxheading{Include files
}
23 \wxheading{Window styles
}
26 \begin{twocollist
}\itemsep=
0pt
27 \twocolitem{\windowstyle{wxLC
\_LIST}}{multicolumn list view, with optional small icons.
28 Columns are computed automatically, i.e. you don't set columns as in wxLC
\_REPORT. In other words,
29 the list wraps, unlike a wxListBox.
}
30 \twocolitem{\windowstyle{wxLC
\_REPORT}}{single or multicolumn
report view, with optional header.
}
31 \twocolitem{\windowstyle{wxLC
\_ICON}}{Large icon view, with optional labels.
}
32 \twocolitem{\windowstyle{wxLC
\_SMALL\_ICON}}{Small icon view, with optional labels.
}
33 \twocolitem{\windowstyle{wxLC
\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only.
}
34 \twocolitem{\windowstyle{wxLC
\_ALIGN\_LEFT}}{Icons align to the left.
}
35 \twocolitem{\windowstyle{wxLC
\_AUTOARRANGE}}{Icons arrange themselves. Win32 only.
}
36 \twocolitem{\windowstyle{wxLC
\_USER\_TEXT}}{The application provides label text on demand, except for column headers. Win32 only.
}
37 \twocolitem{\windowstyle{wxLC
\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.
}
38 \twocolitem{\windowstyle{wxLC
\_NO\_HEADER}}{No header in
report mode. Win32 only.
}
39 \twocolitem{\windowstyle{wxLC
\_SINGLE\_SEL}}{Single selection.
}
40 \twocolitem{\windowstyle{wxLC
\_SORT\_ASCENDING}}{Sort in ascending order (must still supply a comparison callback in SortItems.
}
41 \twocolitem{\windowstyle{wxLC
\_SORT\_DESCENDING}}{Sort in descending order (must still supply a comparison callback in SortItems.
}
44 See also
\helpref{window styles overview
}{windowstyles
}.
46 \wxheading{Event handling
}
48 To process input from a list control, use these event handler macros to direct input to member
49 functions that take a
\helpref{wxListEvent
}{wxlistevent
} argument.
52 \begin{twocollist
}\itemsep=
0pt
53 \twocolitem{{\bf EVT
\_LIST\_BEGIN\_DRAG(id, func)
}}{Begin dragging with the left mouse button.
}
54 \twocolitem{{\bf EVT
\_LIST\_BEGIN\_RDRAG(id, func)
}}{Begin dragging with the right mouse button.
}
55 \twocolitem{{\bf EVT
\_LIST\_BEGIN\_LABEL\_EDIT(id, func)
}}{Begin editing a label. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
56 \twocolitem{{\bf EVT
\_LIST\_END\_LABEL\_EDIT(id, func)
}}{Finish editing a label. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
57 \twocolitem{{\bf EVT
\_LIST\_DELETE\_ITEM(id, func)
}}{Delete an item.
}
58 \twocolitem{{\bf EVT
\_LIST\_DELETE\_ALL\_ITEMS(id, func)
}}{Delete all items.
}
59 \twocolitem{{\bf EVT
\_LIST\_GET\_INFO(id, func)
}}{Request information from the application, usually the item text.
}
60 \twocolitem{{\bf EVT
\_LIST\_SET\_INFO(id, func)
}}{Information is being supplied (not implemented).
}
61 \twocolitem{{\bf EVT
\_LIST\_ITEM\_SELECTED(id, func)
}}{The item has been selected.
}
62 \twocolitem{{\bf EVT
\_LIST\_ITEM\_DESELECTED(id, func)
}}{The item has been deselected.
}
63 \twocolitem{{\bf EVT
\_LIST\_ITEM\_ACTIVATED(id, func)
}}{The item has been activated (ENTER or double click).
}
64 \twocolitem{{\bf EVT
\_LIST\_KEY\_DOWN(id, func)
}}{A key has been pressed.
}
65 \twocolitem{{\bf EVT
\_LIST\_INSERT\_ITEM(id, func)
}}{An item has been inserted.
}
66 \twocolitem{{\bf EVT
\_LIST\_COL\_CLICK(id, func)
}}{A column (
{\bf m
\_col}) has been left-clicked.
}
71 \helpref{wxListCtrl overview
}{wxlistctrloverview
},
\helpref{wxListBox
}{wxlistbox
},
\helpref{wxTreeCtrl
}{wxtreectrl
},
\rtfsp
72 \helpref{wxImageList
}{wximagelist
},
\helpref{wxListEvent
}{wxlistevent
}
74 \latexignore{\rtfignore{\wxheading{Members
}}}
76 \membersection{wxListCtrl::wxListCtrl
}\label{wxlistctrlconstr
}
78 \func{}{wxListCtrl
}{\void}
82 \func{}{wxListCtrl
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
83 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
84 \param{long
}{ style = wxLC
\_ICON},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = ``listCtrl"
}}
86 Constructor, creating and showing a list control.
88 \wxheading{Parameters
}
90 \docparam{parent
}{Parent window. Must not be NULL.
}
92 \docparam{id
}{Window identifier. A value of -
1 indicates a default value.
}
94 \docparam{pos
}{Window position.
}
96 \docparam{size
}{Window size. If the default size (-
1, -
1) is specified then the window is sized
99 \docparam{style
}{Window style. See
\helpref{wxListCtrl
}{wxlistctrl
}.
}
101 \docparam{validator
}{Window validator.
}
103 \docparam{name
}{Window name.
}
107 \helpref{wxListCtrl::Create
}{wxlistctrlcreate
},
\helpref{wxValidator
}{wxvalidator
}
109 \membersection{wxListCtrl::
\destruct{wxListCtrl
}}
111 \func{void
}{\destruct{wxListCtrl
}}{\void}
113 Destructor, destroying the list control.
115 \membersection{wxListCtrl::Arrange
}\label{wxlistctrlarrange
}
117 \func{bool
}{Arrange
}{\param{int
}{flag = wxLIST
\_ALIGN\_DEFAULT}}
119 Arranges the items in icon or small icon view. This only has effect on Win32.
{\it flag
} is one of:
122 \begin{twocollist
}\itemsep=
0pt
123 \twocolitem{wxLIST
\_ALIGN\_DEFAULT}{Default alignment.
}
124 \twocolitem{wxLIST
\_ALIGN\_LEFT}{Align to the left side of the control.
}
125 \twocolitem{wxLIST
\_ALIGN\_TOP}{Align to the top side of the control.
}
126 \twocolitem{wxLIST
\_ALIGN\_SNAP\_TO\_GRID}{Snap to grid.
}
129 \membersection{wxListCtrl::Create
}\label{wxlistctrlcreate
}
131 \func{bool
}{Create
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
132 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
133 \param{long
}{ style = wxLC
\_ICON},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = ``listCtrl"
}}
135 Creates the list control. See
\helpref{wxListCtrl::wxListCtrl
}{wxlistctrlconstr
} for further details.
137 \membersection{wxListCtrl::ClearAll
}\label{wxlistctrlclearall
}
139 \func{void
}{ClearAll
}{}
141 Deletes all items and all columns.
143 \membersection{wxListCtrl::DeleteItem
}\label{wxlistctrldeleteitem
}
145 \func{bool
}{DeleteItem
}{\param{long
}{item
}}
147 Deletes the specified item. This function sends the
148 {\tt wxEVT
\_COMMAND\_LIST\_DELETE\_ITEM} event for the item being deleted.
150 See also:
\helpref{DeleteAllItems
}{wxlistctrldeleteallitems
}
152 \membersection{wxListCtrl::DeleteAllItems
}\label{wxlistctrldeleteallitems
}
154 \func{bool
}{DeleteAllItems
}{}
156 Deletes all the items in the list control.
158 {\bf NB:
} This function does
{\it not
} send the
159 {\tt wxEVT
\_COMMAND\_LIST\_DELETE\_ITEM} event because deleting many items
160 from the control would be too slow then (unlike
\helpref{DeleteItem
}{wxlistctrldeleteitem
}).
162 \membersection{wxListCtrl::DeleteColumn
}\label{wxlistctrldeletecolumn
}
164 \func{bool
}{DeleteColumn
}{\param{int
}{col
}}
168 \membersection{wxListCtrl::EditLabel
}\label{wxlistctrledit
}
170 \func{void
}{EditLabel
}{\param{long
}{item
}}
172 Starts editing the label of the given item. This function generates a
173 EVT
\_LIST\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
174 text control will appear for in-place editing.
176 If the user changed the label (i.e. s/he does not press ESC or leave
177 the text control without changes, a EVT
\_LIST\_END\_LABEL\_EDIT event
178 will be sent which can be vetoed as well.
180 \membersection{wxListCtrl::EnsureVisible
}\label{wxlistctrlensurevisible
}
182 \func{bool
}{EnsureVisible
}{\param{long
}{item
}}
184 Ensures this item is visible.
186 \membersection{wxListCtrl::FindItem
}\label{wxlistctrlfinditem
}
188 \func{long
}{FindItem
}{\param{long
}{start
},
\param{const wxString\&
}{str
},
\param{const bool
}{partial = FALSE
}}
190 Find an item whose label matches this string, starting from the item after
{\it start
} or
191 the beginning if
{\it start
} is -
1.
193 \func{long
}{FindItem
}{\param{long
}{start
},
\param{long
}{data
}}
195 Find an item whose data matches this data, starting from the item after
{\it start
} or
196 the beginning if 'start' is -
1.
198 \func{long
}{FindItem
}{\param{long
}{start
},
\param{const wxPoint\&
}{pt
},
\param{int
}{direction
}}
200 Find an item nearest this position in the specified direction, starting from
201 the item after
{\it start
} or the beginning if
{\it start
} is -
1.
203 \pythonnote{In place of a single overloaded method name, wxPython
204 implements the following methods:
\par
205 \indented{2cm
}{\begin{twocollist
}
206 \twocolitem{{\bf FindItem(start, str, partial=FALSE)
}}{}
207 \twocolitem{{\bf FindItemData(start, data)
}}{}
208 \twocolitem{{\bf FindItemAtPos(start, point, direction)
}}{}
212 \membersection{wxListCtrl::GetColumn
}\label{wxlistctrlgetcolumn
}
214 \constfunc{bool
}{GetColumn
}{\param{int
}{col
},
\param{wxListItem\&
}{item
}}
216 Gets information about this column. See
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
} for more
219 \membersection{wxListCtrl::GetColumnWidth
}\label{wxlistctrlgetcolumnwidth
}
221 \constfunc{int
}{GetColumnWidth
}{\param{int
}{col
}}
223 Gets the column width (
report view only).
225 \membersection{wxListCtrl::GetCountPerPage
}\label{wxlistctrlgetcountperpage
}
227 \constfunc{int
}{GetCountPerPage
}{\void}
229 Gets the number of items that can fit vertically in the
230 visible area of the list control (list or
report view)
231 or the total number of items in the list control (icon
234 \membersection{wxListCtrl::GetEditControl
}\label{wxlistctrlgeteditcontrol
}
236 \constfunc{wxTextCtrl\&
}{GetEditControl
}{\void}
238 Gets the edit control for editing labels.
240 \membersection{wxListCtrl::GetImageList
}\label{wxlistctrlgetimagelist
}
242 \constfunc{wxImageList*
}{GetImageList
}{\param{int
}{which
}}
244 Returns the specified image list.
{\it which
} may be one of:
247 \begin{twocollist
}\itemsep=
0pt
248 \twocolitem{\windowstyle{wxIMAGE
\_LIST\_NORMAL}}{The normal (large icon) image list.
}
249 \twocolitem{\windowstyle{wxIMAGE
\_LIST\_SMALL}}{The small icon image list.
}
250 \twocolitem{\windowstyle{wxIMAGE
\_LIST\_STATE}}{The user-defined state image list (unimplemented).
}
253 \membersection{wxListCtrl::GetItem
}\label{wxlistctrlgetitem
}
255 \constfunc{bool
}{GetItem
}{\param{wxListItem\&
}{info
}}
257 Gets information about the item. See
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
} for more
260 You must call
{\it info.SetId()
} to se ID of item you're interested in
261 before calling this method.
263 \pythonnote{The wxPython version of this method takes an integer parameter
264 for the item ID, and returns the wxListItem object.
267 \membersection{wxListCtrl::GetItemData
}\label{wxlistctrlgetitemdata
}
269 \constfunc{long
}{GetItemData
}{\param{long
}{item
}}
271 Gets the application-defined data associated with this item.
273 \membersection{wxListCtrl::GetItemPosition
}\label{wxlistctrlgetitemposition
}
275 \constfunc{bool
}{GetItemPosition
}{\param{long
}{item
},
\param{wxPoint\&
}{pos
}}
277 Returns the position of the item, in icon or small icon view.
279 \pythonnote{The wxPython version of this method accepts only the item
280 ID and returns the wxPoint.
}
282 \membersection{wxListCtrl::GetItemRect
}\label{wxlistctrlgetitemrect
}
284 \constfunc{bool
}{GetItemRect
}{\param{long
}{item
},
\param{wxRect\&
}{rect
},
\param{int
}{code = wxLIST
\_RECT\_BOUNDS}}
286 Returns the rectangle representing the item's size and position, in client coordinates.
288 {\it code
} is one of wxLIST
\_RECT\_BOUNDS, wxLIST
\_RECT\_ICON, wxLIST
\_RECT\_LABEL.
290 \pythonnote{The wxPython version of this method accepts only the item
291 ID and code and returns the wxRect.
}
293 \membersection{wxListCtrl::GetItemState
}\label{wxlistctrlgetitemstate
}
295 \constfunc{int
}{GetItemState
}{\param{long
}{item
},
\param{long
}{stateMask
}}
297 Gets the item state. For a list of state flags, see
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
}.
299 The
{\bf stateMask
} indicates which state flags are of interest.
301 \membersection{wxListCtrl::GetItemCount
}\label{wxlistctrlgetitemcount
}
303 \constfunc{int
}{GetItemCount
}{\void}
305 Returns the number of items in the list control.
307 \membersection{wxListCtrl::GetItemSpacing
}\label{wxlistctrlgetitemspacing
}
309 \constfunc{int
}{GetItemSpacing
}{\param{bool
}{isSmall
}}
311 Retrieves the spacing between icons in pixels.
312 If
{\it small
} is TRUE, gets the spacing for the small icon
313 view, otherwise the large icon view.
315 \membersection{wxListCtrl::GetItemText
}\label{wxlistctrlgetitemtext
}
317 \constfunc{wxString
}{GetItemText
}{\param{long
}{item
}}
319 Gets the item text for this item.
321 \membersection{wxListCtrl::GetNextItem
}\label{wxlistctrlgetnextitem
}
323 \constfunc{long
}{GetNextItem
}{\param{long
}{item
},
\param{int
}{geometry = wxLIST
\_NEXT\_ALL},
\param{int
}{state = wxLIST
\_STATE\_DONTCARE}}
325 Searches for an item with the given goemetry or state, starting from
326 {\it item
} but excluding the
{\it item
} itself. If
{\it item
} is -
1,
327 the first item that matches the specified flags will be returned.
329 Returns the first item with given state following
{\it item
} or -
1 if
332 This function may be used to find all selected items in the control like this:
338 item = listctrl->GetNextItem(item,
340 wxLIST_STATE_SELECTED);
344 // this item is selected - do whatever is needed with it
345 wxLogMessage("Item
%ld is selected."), item);
349 {\it geometry
} can be one of:
352 \begin{twocollist
}\itemsep=
0pt
353 \twocolitem{wxLIST
\_NEXT\_ABOVE}{Searches for an item above the specified item.
}
354 \twocolitem{wxLIST
\_NEXT\_ALL}{Searches for subsequent item by index.
}
355 \twocolitem{wxLIST
\_NEXT\_BELOW}{Searches for an item below the specified item.
}
356 \twocolitem{wxLIST
\_NEXT\_LEFT}{Searches for an item to the left of the specified item.
}
357 \twocolitem{wxLIST
\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.
}
360 {\bf NB:
} this parameters is only supported by wxMSW currently and ignored on
363 {\it state
} can be a bitlist of the following:
366 \begin{twocollist
}\itemsep=
0pt
367 \twocolitem{wxLIST
\_STATE\_DONTCARE}{Don't care what the state is.
}
368 \twocolitem{wxLIST
\_STATE\_DROPHILITED}{The item indicates it is a drop target.
}
369 \twocolitem{wxLIST
\_STATE\_FOCUSED}{The item has the focus.
}
370 \twocolitem{wxLIST
\_STATE\_SELECTED}{The item is selected.
}
371 \twocolitem{wxLIST
\_STATE\_CUT}{The item is selected as part of a cut and paste operation.
}
374 \membersection{wxListCtrl::GetSelectedItemCount
}\label{wxlistctrlgetselecteditemcount
}
376 \constfunc{int
}{GetSelectedItemCount
}{\void}
378 Returns the number of selected items in the list control.
380 \membersection{wxListCtrl::GetTextColour
}\label{wxlistctrlgettextcolour
}
382 \constfunc{wxColour
}{GetTextColour
}{\void}
384 Gets the text colour of the list control.
386 \membersection{wxListCtrl::GetTopItem
}\label{wxlistctrlgettopitem
}
388 \constfunc{long
}{GetTopItem
}{\void}
390 Gets the index of the topmost visible item when in
393 \membersection{wxListCtrl::HitTest
}\label{wxlistctrlhittest
}
395 \func{long
}{HitTest
}{\param{const wxPoint\&
}{point
},
\param{int\&
}{flags
}}
397 Determines which item (if any) is at the specified point,
398 giving details in
{\it flags
}.
{\it flags
} will be a combination of the following flags:
401 \begin{twocollist
}\itemsep=
0pt
402 \twocolitem{wxLIST
\_HITTEST\_ABOVE}{Above the client area.
}
403 \twocolitem{wxLIST
\_HITTEST\_BELOW}{Below the client area.
}
404 \twocolitem{wxLIST
\_HITTEST\_NOWHERE}{In the client area but below the last item.
}
405 \twocolitem{wxLIST
\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.
}
406 \twocolitem{wxLIST
\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.
}
407 \twocolitem{wxLIST
\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.
}
408 \twocolitem{wxLIST
\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.
}
409 \twocolitem{wxLIST
\_HITTEST\_TOLEFT}{To the right of the client area.
}
410 \twocolitem{wxLIST
\_HITTEST\_TORIGHT}{To the left of the client area.
}
411 \twocolitem{wxLIST
\_HITTEST\_ONITEM}{Combination of wxLIST
\_HITTEST\_ONITEMICON, wxLIST
\_HITTEST\_ONITEMLABEL,
412 wxLIST
\_HITTEST\_ONITEMSTATEICON.
}
415 \pythonnote{A tuple of values is returned in the wxPython version of
416 this method. The first value is the item id and the second is the
417 flags value mentioned above.
}
419 \membersection{wxListCtrl::InsertColumn
}\label{wxlistctrlinsertcolumn
}
421 \func{long
}{InsertColumn
}{\param{long
}{col
},
\param{wxListItem\&
}{info
}}
423 For list view mode (only), inserts a column. For more details, see
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
}.
425 \func{long
}{InsertColumn
}{\param{long
}{col
},
\param{const wxString\&
}{heading
},
\param{int
}{format = wxLIST
\_FORMAT\_LEFT},
\rtfsp
426 \param{int
}{width = -
1}}
428 For list view mode (only), inserts a column. For more details, see
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
}.
430 \pythonnote{In place of a single overloaded method name, wxPython
431 implements the following methods:
\par
432 \indented{2cm
}{\begin{twocollist
}
433 \twocolitem{{\bf InsertColumn(col, heading, format=wxLIST
\_FORMAT\_LEFT,
434 width=-
1)
}}{Creates a column using a header string only.
}
435 \twocolitem{{\bf InsertColumnInfo(col, item)
}}{Creates a column using a
440 \membersection{wxListCtrl::InsertItem
}\label{wxlistctrlinsertitem
}
442 \func{long
}{InsertItem
}{\param{wxListItem\&
}{info
}}
444 Inserts an item, returning the index of the new item if successful,
447 \func{long
}{InsertItem
}{\param{long
}{index
},
\param{const wxString\&
}{label
}}
449 Inserts a string item.
451 \func{long
}{InsertItem
}{\param{long
}{index
},
\param{int
}{imageIndex
}}
453 Inserts an image item.
455 \func{long
}{InsertItem
}{\param{long
}{index
},
\param{const wxString\&
}{label
},
\param{int
}{imageIndex
}}
457 Insert an image/string item.
459 \wxheading{Parameters
}
461 \docparam{info
}{wxListItem object
}
463 \docparam{index
}{Index of the new item, supplied by the application
}
465 \docparam{label
}{String label
}
467 \docparam{imageIndex
}{index into the image list associated with this control and view style
}
469 \pythonnote{In place of a single overloaded method name, wxPython
470 implements the following methods:
\par
471 \indented{2cm
}{\begin{twocollist
}\itemsep=
0pt
472 \twocolitem{{\bf InsertItem(item)
}}{Inserts an item using a wxListItem.
}
473 \twocolitem{{\bf InsertStringItem(index, label)
}}{Inserts a string item.
}
474 \twocolitem{{\bf InsertImageItem(index, imageIndex)
}}{Inserts an image item.
}
475 \twocolitem{{\bf InsertImageStringItem(index, label, imageIndex)
}}{Insert an image/string item.
}
479 \membersection{wxListCtrl::ScrollList
}\label{wxlistctrlscrolllist
}
481 \func{bool
}{ScrollList
}{\param{int
}{dx
},
\param{int
}{dy
}}
483 Scrolls the list control. If in icon, small icon or
report view mode,
484 dx specifies the number of pixels to scroll. If in list view mode, dx
485 specifies the number of columns to scroll.
487 If in icon, small icon or list view mode, dy specifies the number of pixels
488 to scroll. If in
report view mode, dy specifies the number of lines to scroll.
490 \membersection{wxListCtrl::SetBackgroundColour
}\label{wxlistctrlsetbackgroundcolour
}
492 \func{void
}{SetBackgroundColour
}{\param{const wxColour\&
}{col
}}
494 Sets the background colour (GetBackgroundColour already implicit in
497 \membersection{wxListCtrl::SetColumn
}\label{wxlistctrlsetcolumn
}
499 \func{bool
}{SetColumn
}{\param{int
}{col
},
\param{wxListItem\&
}{item
}}
501 Sets information about this column. See
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
} for more
504 \membersection{wxListCtrl::SetColumnWidth
}\label{wxlistctrlsetcolumnwidth
}
506 \func{bool
}{SetColumnWidth
}{\param{int
}{col
},
\param{int
}{width
}}
508 Sets the column width.
510 {\it width
} can be a width in pixels or wxLIST
\_AUTOSIZE (-
1) or wxLIST
\_AUTOSIZE\_USEHEADER (-
2).
511 wxLIST
\_AUTOSIZE will resize the column to the length of its longest item. wxLIST
\_AUTOSIZE\_USEHEADER
512 will resize the column to the length of the header (Win32) or
80 pixels (other platforms).
514 In small or normal icon view,
{\it col
} must be -
1, and the column width is set for all columns.
516 \membersection{wxListCtrl::SetImageList
}\label{wxlistctrlsetimagelist
}
518 \func{void
}{SetImageList
}{\param{wxImageList*
}{ imageList
},
\param{int
}{which
}}
520 Sets the image list associated with the control.
{\it which
} is one of
521 wxIMAGE
\_LIST\_NORMAL, wxIMAGE
\_LIST\_SMALL, wxIMAGE
\_LIST\_STATE (the last is unimplemented).
523 \membersection{wxListCtrl::SetItem
}\label{wxlistctrlsetitem
}
525 \func{bool
}{SetItem
}{\param{wxListItem\&
}{info
}}
527 \func{long
}{SetItem
}{\param{long
}{index
},
\param{int
}{col
},
\param{const
}{wxString\& label
},
\param{int
}{imageId = -
1}}
529 Sets information about the item.
531 wxListItem is a class with the following members:
534 \begin{twocollist
}\itemsep=
0pt
535 \twocolitem{long m
\_mask}{Indicates which fields are valid. See the list of valid mask flags below.
}
536 \twocolitem{long m
\_itemId}{The zero-based item position.
}
537 \twocolitem{int m
\_col}{Zero-based column, if in
report mode.
}
538 \twocolitem{long m
\_state}{The state of the item. See the list of valid state flags below.
}
539 \twocolitem{long m
\_stateMask}{A mask indicating which state flags are valid. See the list of valid state flags below.
}
540 \twocolitem{wxString m
\_text}{The label/header text.
}
541 \twocolitem{int m
\_image}{The zero-based index into an image list.
}
542 \twocolitem{long m
\_data}{Application-defined data.
}
543 \twocolitem{int m
\_format}{For columns only: the format. Can be wxLIST
\_FORMAT\_LEFT, wxLIST
\_FORMAT\_RIGHT or
544 wxLIST
\_FORMAT\_CENTRE.
}
545 \twocolitem{int m
\_width}{For columns only: the column width.
}
548 The
{\bf m
\_mask} member contains a bitlist specifying which of the other fields are valid. The flags are:
551 \begin{twocollist
}\itemsep=
0pt
552 \twocolitem{wxLIST
\_MASK\_STATE}{The
{\bf m
\_state} field is valid.
}
553 \twocolitem{wxLIST
\_MASK\_TEXT}{The
{\bf m
\_text} field is valid.
}
554 \twocolitem{wxLIST
\_MASK\_IMAGE}{The
{\bf m
\_image} field is valid.
}
555 \twocolitem{wxLIST
\_MASK\_DATA}{The
{\bf m
\_data} field is valid.
}
556 \twocolitem{wxLIST
\_MASK\_WIDTH}{The
{\bf m
\_width} field is valid.
}
557 \twocolitem{wxLIST
\_MASK\_FORMAT}{The
{\bf m
\_format} field is valid.
}
560 The
{\bf m
\_stateMask} and
{\bf m
\_state} members take flags from the following:
562 The wxListItem object can also contain item-specific colour and font
563 information: for this you need to call one of SetTextColour(),
564 SetBackgroundColour() or SetFont() functions on it passing it the colour/font
565 to use. If the colour/font is not specified, the default list control
569 \begin{twocollist
}\itemsep=
0pt
570 \twocolitem{wxLIST
\_STATE\_DONTCARE}{Don't care what the state is. Win32 only.
}
571 \twocolitem{wxLIST
\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event. Win32 only.
}
572 \twocolitem{wxLIST
\_STATE\_FOCUSED}{The item has the focus.
}
573 \twocolitem{wxLIST
\_STATE\_SELECTED}{The item is selected.
}
574 \twocolitem{wxLIST
\_STATE\_CUT}{The item is in the cut state. Win32 only.
}
577 \func{long
}{SetItem
}{\param{long
}{index
},
\param{int
}{col
},
\param{const wxString\&
}{label
},
\param{int
}{imageId = -
1}}
579 Sets a string field at a particular column.
581 \pythonnote{In place of a single overloaded method name, wxPython
582 implements the following methods:
\par
583 \indented{2cm
}{\begin{twocollist
}
584 \twocolitem{{\bf SetItem(item)
}}{Sets information about the given wxListItem.
}
585 \twocolitem{{\bf SetStringItem(index, col, label, imageId)
}}{Sets a
586 string or image at a given location.
}
590 \membersection{wxListCtrl::SetItemData
}\label{wxlistctrlsetitemdata
}
592 \func{bool
}{SetItemData
}{\param{long
}{item
},
\param{long
}{data
}}
594 Associates application-defined data with this item.
596 \membersection{wxListCtrl::SetItemImage
}\label{wxlistctrlsetitemimage
}
598 \func{bool
}{SetItemImage
}{\param{long
}{item
},
\param{int
}{image
},
\param{int
}{selImage
}}
600 Sets the unselected and selected images associated with the item. The images are indices into the
601 image list associated with the list control.
603 \membersection{wxListCtrl::SetItemPosition
}\label{wxlistctrlsetitemposition
}
605 \func{bool
}{SetItemPosition
}{\param{long
}{item
},
\param{const wxPoint\&
}{pos
}}
607 Sets the position of the item, in icon or small icon view.
609 \membersection{wxListCtrl::SetItemState
}\label{wxlistctrlsetitemstate
}
611 \func{bool
}{SetItemState
}{\param{long
}{item
},
\param{long
}{state
},
\param{long
}{stateMask
}}
613 Sets the item state. For a list of state flags, see
\helpref{wxListCtrl::SetItem
}{wxlistctrlsetitem
}.
615 The
{\bf stateMask
} indicates which state flags are valid.
617 \membersection{wxListCtrl::SetItemText
}\label{wxlistctrlsetitemtext
}
619 \func{void
}{SetItemText
}{\param{long
}{item
},
\param{const wxString\&
}{text
}}
621 Sets the item text for this item.
623 \membersection{wxListCtrl::SetSingleStyle
}\label{wxlistctrlsetsinglestyle
}
625 \func{void
}{SetSingleStyle
}{\param{long
}{style
},
\param{const bool
}{add = TRUE
}}
627 Adds or removes a single window style.
629 \membersection{wxListCtrl::SetTextColour
}\label{wxlistctrlsettextcolour
}
631 \func{void
}{SetTextColour
}{\param{const wxColour\&
}{col
}}
633 Sets the text colour of the list control.
635 \membersection{wxListCtrl::SetWindowStyleFlag
}\label{wxlistctrlsetwindowstyleflag
}
637 \func{void
}{SetWindowStyleFlag
}{\param{long
}{style
}}
639 Sets the whole window style.
641 \membersection{wxListCtrl::SortItems
}\label{wxlistctrlsortitems
}
643 \func{bool
}{SortItems
}{\param{wxListCtrlCompare
}{fnSortCallBack
},
\param{long
}{data
}}
645 Call this function to sort the items in the list control. Sorting is done
646 using the specified
{\it fnSortCallBack
} function. This function must have the
650 int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
653 It is called each time when the two items must be compared and should return
0
654 if the items are equal, negative value if the first item is less than the
655 second one and positive value if the first one is greater than the second one
656 (the same convention as used by
{\tt qsort(
3)
}).
658 \wxheading{Parameters
}
660 \docparam{item1
}{client data associated with the first item (
{\bf NOT
} the index).
}
662 \docparam{item2
}{client data associated with the second item (
{\bf NOT
} the index).
}
664 \docparam{data
}{the value passed to SortItems() itself.
}
666 Notice that the control may only be sorted on client data associated with the
667 items, so you
{\bf must
} use
\helpref{SetItemData
}{wxlistctrlsetitemdata
} if
668 you want to be able to sort the items in the control.
670 Please see the
\helpref{listctrl sample
}{samplelistctrl
} for an example of
673 \pythonnote{wxPython uses the sortData parameter to pass the Python
674 function to call, so it is not available for programmer use. Call
675 SortItems with a reference to a callable object that expects two