docs/latex/wx/listctrl.tex

   1 \section{\class{wxListCtrl}}\label{wxlistctrl}
   2
   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.
   5 For all these modes, the items are stored in the control and must be added to
   6 it using \helpref{InsertItem}{wxlistctrlinsertitem} method.
   7
   8 A special case of report view quite different from the other modes of the list
   9 control is a virtual control in which the items data (including text, images
  10 and attributes) is managed by the main program and is requested by the control
  11 itself only when needed which allows to have controls with millions of items
  12 without consuming much memory. To use virtual list control you must use
  13 \helpref{SetItemCount}{wxlistctrlsetitemcount} first and overload at least
  14 \helpref{OnGetItemText}{wxlistctrlongetitemtext} (and optionally
  15 \helpref{OnGetItemImage}{wxlistctrlongetitemimage} and
  16 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}) to return the information
  17 about the items when the control requests it.
  18
  19 Using many of wxListCtrl features is shown in the
  20 \helpref{corresponding sample}{samplelistctrl}.
  21
  22 To intercept events from a list control, use the event table macros described
  23 in \helpref{wxListEvent}{wxlistevent}.
  24
  25 \wxheading{Derived from}
  26
  27 \helpref{wxControl}{wxcontrol}\\
  28 \helpref{wxWindow}{wxwindow}\\
  29 \helpref{wxEvtHandler}{wxevthandler}\\
  30 \helpref{wxObject}{wxobject}
  31
  32 \wxheading{Include files}
  33
  34 <wx/listctrl.h>
  35
  36 \wxheading{Window styles}
  37
  38 \twocolwidtha{7cm}
  39 \begin{twocollist}\itemsep=0pt
  40 \twocolitem{\windowstyle{wxLC\_LIST}}{multicolumn list view, with optional small icons.
  41 Columns are computed automatically, i.e. you don't set columns as in wxLC\_REPORT. In other words,
  42 the list wraps, unlike a wxListBox.}
  43 \twocolitem{\windowstyle{wxLC\_REPORT}}{single or multicolumn report view, with optional header.}
  44 \twocolitem{\windowstyle{wxLC\_VIRTUAL}}{virtual control, may only be used with wxLC\_REPORT}
  45 \twocolitem{\windowstyle{wxLC\_ICON}}{Large icon view, with optional labels.}
  46 \twocolitem{\windowstyle{wxLC\_SMALL\_ICON}}{Small icon view, with optional labels.}
  47 \twocolitem{\windowstyle{wxLC\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only. }
  48 \twocolitem{\windowstyle{wxLC\_ALIGN\_LEFT}}{Icons align to the left. }
  49 \twocolitem{\windowstyle{wxLC\_AUTOARRANGE}}{Icons arrange themselves. Win32 only. }
  50 \twocolitem{\windowstyle{wxLC\_USER\_TEXT}}{The application provides label text on demand, except for column headers. Win32 only. }
  51 \twocolitem{\windowstyle{wxLC\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.}
  52 \twocolitem{\windowstyle{wxLC\_NO\_HEADER}}{No header in report mode. Win32 only. }
  53 \twocolitem{\windowstyle{wxLC\_SINGLE\_SEL}}{Single selection.}
  54 \twocolitem{\windowstyle{wxLC\_SORT\_ASCENDING}}{Sort in ascending order (must still supply a comparison callback in SortItems.}
  55 \twocolitem{\windowstyle{wxLC\_SORT\_DESCENDING}}{Sort in descending order (must still supply a comparison callback in SortItems.}
  56 \twocolitem{\windowstyle{wxLC\_HRULES}}{Draws light horizontal rules between rows in report mode.}
  57 \twocolitem{\windowstyle{wxLC\_VRULES}}{Draws light vertical rules between columns in report mode.}
  58 \end{twocollist}
  59
  60 See also \helpref{window styles overview}{windowstyles}.
  61
  62 \wxheading{Event handling}
  63
  64 To process input from a list control, use these event handler macros to direct input to member
  65 functions that take a \helpref{wxListEvent}{wxlistevent} argument.
  66
  67 \twocolwidtha{7cm}
  68 \begin{twocollist}\itemsep=0pt
  69 \twocolitem{{\bf EVT\_LIST\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
  70 \twocolitem{{\bf EVT\_LIST\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
  71 \twocolitem{{\bf EVT\_LIST\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  72 \twocolitem{{\bf EVT\_LIST\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  73 \twocolitem{{\bf EVT\_LIST\_DELETE\_ITEM(id, func)}}{Delete an item.}
  74 \twocolitem{{\bf EVT\_LIST\_DELETE\_ALL\_ITEMS(id, func)}}{Delete all items.}
  75 %\twocolitem{{\bf EVT\_LIST\_GET\_INFO(id, func)}}{Request information from the application, usually the item text.}
  76 %\twocolitem{{\bf EVT\_LIST\_SET\_INFO(id, func)}}{Information is being supplied (not implemented).}
  77 \twocolitem{{\bf EVT\_LIST\_ITEM\_SELECTED(id, func)}}{The item has been selected.}
  78 \twocolitem{{\bf EVT\_LIST\_ITEM\_DESELECTED(id, func)}}{The item has been deselected.}
  79 \twocolitem{{\bf EVT\_LIST\_ITEM\_ACTIVATED(id, func)}}{The item has been activated (ENTER or double click).}
  80 \twocolitem{{\bf EVT\_LIST\_ITEM\_FOCUSED(id, func)}}{The currently focused item has changed.}
  81 \twocolitem{{\bf EVT\_LIST\_ITEM\_MIDDLE\_CLICK(id, func)}}{The middle mouse button has been clicked on an item.}
  82 \twocolitem{{\bf EVT\_LIST\_ITEM\_RIGHT\_CLICK(id, func)}}{The right mouse button has been clicked on an item.}
  83 \twocolitem{{\bf EVT\_LIST\_KEY\_DOWN(id, func)}}{A key has been pressed.}
  84 \twocolitem{{\bf EVT\_LIST\_INSERT\_ITEM(id, func)}}{An item has been inserted.}
  85 \twocolitem{{\bf EVT\_LIST\_COL\_CLICK(id, func)}}{A column ({\bf m\_col}) has been left-clicked.}
  86 \twocolitem{{\bf EVT\_LIST\_COL\_RIGHT\_CLICK(id, func)}}{A column ({\bf m\_col}) has been right-clicked.}
  87 \twocolitem{{\bf EVT\_LIST\_COL\_BEGIN\_DRAG(id, func)}}{The user started resizing a column - can be vetoed.}
  88 \twocolitem{{\bf EVT\_LIST\_COL\_DRAGGING(id, func)}}{The divider between columns is being dragged.}
  89 \twocolitem{{\bf EVT\_LIST\_COL\_END\_DRAG(id, func)}}{A column has been resized by the user.}
  90 \twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control}
  91 \end{twocollist}%
  92
  93 \wxheading{See also}
  94
  95 \helpref{wxListCtrl overview}{wxlistctrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxTreeCtrl}{wxtreectrl},\rtfsp
  96 \helpref{wxImageList}{wximagelist}, \helpref{wxListEvent}{wxlistevent},
  97 \helpref{wxListItem}{wxlistitem}
  98
  99 \latexignore{\rtfignore{\wxheading{Members}}}
 100
 101 \membersection{wxListCtrl::wxListCtrl}\label{wxlistctrlconstr}
 102
 103 \func{}{wxListCtrl}{\void}
 104
 105 Default constructor.
 106
 107 \func{}{wxListCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 108 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 109 \param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 110
 111 Constructor, creating and showing a list control.
 112
 113 \wxheading{Parameters}
 114
 115 \docparam{parent}{Parent window. Must not be NULL.}
 116
 117 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
 118
 119 \docparam{pos}{Window position.}
 120
 121 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 122 appropriately.}
 123
 124 \docparam{style}{Window style. See \helpref{wxListCtrl}{wxlistctrl}.}
 125
 126 \docparam{validator}{Window validator.}
 127
 128 \docparam{name}{Window name.}
 129
 130 \wxheading{See also}
 131
 132 \helpref{wxListCtrl::Create}{wxlistctrlcreate}, \helpref{wxValidator}{wxvalidator}
 133
 134 \membersection{wxListCtrl::\destruct{wxListCtrl}}
 135
 136 \func{void}{\destruct{wxListCtrl}}{\void}
 137
 138 Destructor, destroying the list control.
 139
 140 \membersection{wxListCtrl::Arrange}\label{wxlistctrlarrange}
 141
 142 \func{bool}{Arrange}{\param{int }{flag = wxLIST\_ALIGN\_DEFAULT}}
 143
 144 Arranges the items in icon or small icon view. This only has effect on Win32. {\it flag} is one of:
 145
 146 \twocolwidtha{5cm}
 147 \begin{twocollist}\itemsep=0pt
 148 \twocolitem{wxLIST\_ALIGN\_DEFAULT}{Default alignment.}
 149 \twocolitem{wxLIST\_ALIGN\_LEFT}{Align to the left side of the control.}
 150 \twocolitem{wxLIST\_ALIGN\_TOP}{Align to the top side of the control.}
 151 \twocolitem{wxLIST\_ALIGN\_SNAP\_TO\_GRID}{Snap to grid.}
 152 \end{twocollist}
 153
 154 \membersection{wxListCtrl::AssignImageList}\label{wxlistctrlassignimagelist}
 155
 156 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
 157
 158 Sets the image list associated with the control and
 159 takes ownership of it (i.e. the control will, unlike when using
 160 SetImageList, delete the list when destroyed). {\it which} is one of
 161 wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).
 162
 163 \wxheading{See also}
 164
 165 \helpref{wxListCtrl::SetImageList}{wxlistctrlsetimagelist}
 166
 167 \membersection{wxListCtrl::ClearAll}\label{wxlistctrlclearall}
 168
 169 \func{void}{ClearAll}{}
 170
 171 Deletes all items and all columns.
 172
 173 \membersection{wxListCtrl::Create}\label{wxlistctrlcreate}
 174
 175 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 176 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 177 \param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 178
 179 Creates the list control. See \helpref{wxListCtrl::wxListCtrl}{wxlistctrlconstr} for further details.
 180
 181 \membersection{wxListCtrl::DeleteAllItems}\label{wxlistctrldeleteallitems}
 182
 183 \func{bool}{DeleteAllItems}{}
 184
 185 Deletes all the items in the list control.
 186
 187 {\bf NB:} This function does {\it not} send the
 188 {\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event because deleting many items
 189 from the control would be too slow then (unlike \helpref{DeleteItem}{wxlistctrldeleteitem}).
 190
 191 \membersection{wxListCtrl::DeleteColumn}\label{wxlistctrldeletecolumn}
 192
 193 \func{bool}{DeleteColumn}{\param{int }{col}}
 194
 195 Deletes a column.
 196
 197 \membersection{wxListCtrl::DeleteItem}\label{wxlistctrldeleteitem}
 198
 199 \func{bool}{DeleteItem}{\param{long }{item}}
 200
 201 Deletes the specified item. This function sends the
 202 {\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event for the item being deleted.
 203
 204 See also: \helpref{DeleteAllItems}{wxlistctrldeleteallitems}
 205
 206 \membersection{wxListCtrl::EditLabel}\label{wxlistctrledit}
 207
 208 \func{void}{EditLabel}{\param{long }{item}}
 209
 210 Starts editing the label of the given item. This function generates a
 211 EVT\_LIST\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
 212 text control will appear for in-place editing.
 213
 214 If the user changed the label (i.e. s/he does not press ESC or leave
 215 the text control without changes, a EVT\_LIST\_END\_LABEL\_EDIT event
 216 will be sent which can be vetoed as well.
 217
 218 \membersection{wxListCtrl::EnsureVisible}\label{wxlistctrlensurevisible}
 219
 220 \func{bool}{EnsureVisible}{\param{long }{item}}
 221
 222 Ensures this item is visible.
 223
 224 \membersection{wxListCtrl::FindItem}\label{wxlistctrlfinditem}
 225
 226 \func{long}{FindItem}{\param{long }{start}, \param{const wxString\& }{str}, \param{const bool }{partial = FALSE}}
 227
 228 Find an item whose label matches this string, starting from the item after {\it start} or
 229 the beginning if {\it start} is -1.
 230
 231 \func{long}{FindItem}{\param{long }{start}, \param{long }{data}}
 232
 233 Find an item whose data matches this data, starting from the item after {\it start} or
 234 the beginning if 'start' is -1.
 235
 236 \func{long}{FindItem}{\param{long }{start}, \param{const wxPoint\& }{pt}, \param{int }{direction}}
 237
 238 Find an item nearest this position in the specified direction, starting from
 239 the item after {\it start} or the beginning if {\it start} is -1.
 240
 241 \pythonnote{In place of a single overloaded method name, wxPython
 242 implements the following methods:\par
 243 \indented{2cm}{\begin{twocollist}
 244 \twocolitem{{\bf FindItem(start, str, partial=FALSE)}}{}
 245 \twocolitem{{\bf FindItemData(start, data)}}{}
 246 \twocolitem{{\bf FindItemAtPos(start, point, direction)}}{}
 247 \end{twocollist}}
 248 }
 249
 250 \perlnote{In wxPerl there are three methods instead of a single overloaded
 251 method:\par
 252 \indented{2cm}{\begin{twocollist}
 253 \twocolitem{{\bf FindItem( start, str, partial = FALSE ) }}{}
 254 \twocolitem{{\bf FindItemData( start, data ) }}{}
 255 \twocolitem{{\bf FindItemAtPos( start, point, direction )}}{}
 256 \end{twocollist}
 257 }}
 258
 259 \membersection{wxListCtrl::GetColumn}\label{wxlistctrlgetcolumn}
 260
 261 \constfunc{bool}{GetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
 262
 263 Gets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
 264 information.
 265
 266 \perlnote{In wxPerl this method takes only the {\bf col} parameter and
 267   returns a Wx::ListItem ( or undef ).}
 268
 269 \membersection{wxListCtrl::GetColumnWidth}\label{wxlistctrlgetcolumnwidth}
 270
 271 \constfunc{int}{GetColumnWidth}{\param{int }{col}}
 272
 273 Gets the column width (report view only).
 274
 275 \membersection{wxListCtrl::GetCountPerPage}\label{wxlistctrlgetcountperpage}
 276
 277 \constfunc{int}{GetCountPerPage}{\void}
 278
 279 Gets the number of items that can fit vertically in the
 280 visible area of the list control (list or report view)
 281 or the total number of items in the list control (icon
 282 or small icon view).
 283
 284 \membersection{wxListCtrl::GetEditControl}\label{wxlistctrlgeteditcontrol}
 285
 286 \constfunc{wxTextCtrl\&}{GetEditControl}{\void}
 287
 288 Gets the edit control for editing labels.
 289
 290 \membersection{wxListCtrl::GetImageList}\label{wxlistctrlgetimagelist}
 291
 292 \constfunc{wxImageList*}{GetImageList}{\param{int }{which}}
 293
 294 Returns the specified image list. {\it which} may be one of:
 295
 296 \twocolwidtha{5cm}
 297 \begin{twocollist}\itemsep=0pt
 298 \twocolitem{\windowstyle{wxIMAGE\_LIST\_NORMAL}}{The normal (large icon) image list.}
 299 \twocolitem{\windowstyle{wxIMAGE\_LIST\_SMALL}}{The small icon image list.}
 300 \twocolitem{\windowstyle{wxIMAGE\_LIST\_STATE}}{The user-defined state image list (unimplemented).}
 301 \end{twocollist}
 302
 303 \membersection{wxListCtrl::GetItem}\label{wxlistctrlgetitem}
 304
 305 \constfunc{bool}{GetItem}{\param{wxListItem\& }{info}}
 306
 307 Gets information about the item. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
 308 information.
 309
 310 You must call {\it info.SetId()} to the ID of item you're interested in
 311 before calling this method.
 312
 313 \pythonnote{The wxPython version of this method takes an integer parameter
 314 for the item ID, an optional integer for the column number, and
 315 returns the wxListItem object.}
 316
 317 \perlnote{In wxPerl this method takes as parameter the {\bf ID} of the item
 318 and ( optionally ) the column, and returns a Wx::ListItem object.}
 319
 320 \membersection{wxListCtrl::GetItemCount}\label{wxlistctrlgetitemcount}
 321
 322 \constfunc{int}{GetItemCount}{\void}
 323
 324 Returns the number of items in the list control.
 325
 326 \membersection{wxListCtrl::GetItemData}\label{wxlistctrlgetitemdata}
 327
 328 \constfunc{long}{GetItemData}{\param{long }{item}}
 329
 330 Gets the application-defined data associated with this item.
 331
 332 \membersection{wxListCtrl::GetItemPosition}\label{wxlistctrlgetitemposition}
 333
 334 \constfunc{bool}{GetItemPosition}{\param{long }{item}, \param{wxPoint\& }{pos}}
 335
 336 Returns the position of the item, in icon or small icon view.
 337
 338 \pythonnote{The wxPython version of this method accepts only the item
 339 ID and returns the wxPoint.}
 340
 341 \perlnote{In wxPerl this method takes only the {\bf item} parameter and
 342 returns a Wx::Point ( or undef ).}
 343
 344 \membersection{wxListCtrl::GetItemRect}\label{wxlistctrlgetitemrect}
 345
 346 \constfunc{bool}{GetItemRect}{\param{long }{item}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
 347
 348 Returns the rectangle representing the item's size and position, in client coordinates.
 349
 350 {\it code} is one of wxLIST\_RECT\_BOUNDS, wxLIST\_RECT\_ICON, wxLIST\_RECT\_LABEL.
 351
 352 \pythonnote{The wxPython version of this method accepts only the item
 353 ID and code and returns the wxRect.}
 354
 355 \perlnote{In wxPerl this method takes only the {\bf item} parameter and
 356 retutrns a Wx::Rect ( or undef ).}
 357
 358 \membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
 359
 360 \constfunc{int}{GetItemSpacing}{\param{bool }{isSmall}}
 361
 362 Retrieves the spacing between icons in pixels.
 363 If {\it small} is TRUE, gets the spacing for the small icon
 364 view, otherwise the large icon view.
 365
 366 \membersection{wxListCtrl::GetItemState}\label{wxlistctrlgetitemstate}
 367
 368 \constfunc{int}{GetItemState}{\param{long }{item}, \param{long }{stateMask}}
 369
 370 Gets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
 371
 372 The {\bf stateMask} indicates which state flags are of interest.
 373
 374 \membersection{wxListCtrl::GetItemText}\label{wxlistctrlgetitemtext}
 375
 376 \constfunc{wxString}{GetItemText}{\param{long }{item}}
 377
 378 Gets the item text for this item.
 379
 380 \membersection{wxListCtrl::GetNextItem}\label{wxlistctrlgetnextitem}
 381
 382 \constfunc{long}{GetNextItem}{\param{long }{item}, \param{int }{geometry = wxLIST\_NEXT\_ALL}, \param{int }{state = wxLIST\_STATE\_DONTCARE}}
 383
 384 Searches for an item with the given goemetry or state, starting from
 385 {\it item} but excluding the {\it item} itself. If {\it item} is -1,
 386 the first item that matches the specified flags will be returned.
 387
 388 Returns the first item with given state following {\it item} or -1 if
 389 no such item found.
 390
 391 This function may be used to find all selected items in the control like this:
 392
 393 \begin{verbatim}
 394     long item = -1;
 395     for ( ;; )
 396     {
 397         item = listctrl->GetNextItem(item,
 398                                      wxLIST_NEXT_ALL,
 399                                      wxLIST_STATE_SELECTED);
 400         if ( item == -1 )
 401             break;
 402
 403         // this item is selected - do whatever is needed with it
 404         wxLogMessage("Item %ld is selected."), item);
 405     }
 406 \end{verbatim}
 407
 408 {\it geometry} can be one of:
 409
 410 \twocolwidtha{5cm}
 411 \begin{twocollist}\itemsep=0pt
 412 \twocolitem{wxLIST\_NEXT\_ABOVE}{Searches for an item above the specified item.}
 413 \twocolitem{wxLIST\_NEXT\_ALL}{Searches for subsequent item by index.}
 414 \twocolitem{wxLIST\_NEXT\_BELOW}{Searches for an item below the specified item.}
 415 \twocolitem{wxLIST\_NEXT\_LEFT}{Searches for an item to the left of the specified item.}
 416 \twocolitem{wxLIST\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.}
 417 \end{twocollist}
 418
 419 {\bf NB:} this parameters is only supported by wxMSW currently and ignored on
 420 other platforms.
 421
 422 {\it state} can be a bitlist of the following:
 423
 424 \twocolwidtha{5cm}
 425 \begin{twocollist}\itemsep=0pt
 426 \twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is.}
 427 \twocolitem{wxLIST\_STATE\_DROPHILITED}{The item indicates it is a drop target.}
 428 \twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
 429 \twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
 430 \twocolitem{wxLIST\_STATE\_CUT}{The item is selected as part of a cut and paste operation.}
 431 \end{twocollist}
 432
 433 \membersection{wxListCtrl::GetSelectedItemCount}\label{wxlistctrlgetselecteditemcount}
 434
 435 \constfunc{int}{GetSelectedItemCount}{\void}
 436
 437 Returns the number of selected items in the list control.
 438
 439 \membersection{wxListCtrl::GetTextColour}\label{wxlistctrlgettextcolour}
 440
 441 \constfunc{wxColour}{GetTextColour}{\void}
 442
 443 Gets the text colour of the list control.
 444
 445 \membersection{wxListCtrl::GetTopItem}\label{wxlistctrlgettopitem}
 446
 447 \constfunc{long}{GetTopItem}{\void}
 448
 449 Gets the index of the topmost visible item when in
 450 list or report view.
 451
 452 \membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
 453
 454 \func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 455
 456 Determines which item (if any) is at the specified point,
 457 giving details in {\it flags}. {\it flags} will be a combination of the following flags:
 458
 459 \twocolwidtha{5cm}
 460 \begin{twocollist}\itemsep=0pt
 461 \twocolitem{wxLIST\_HITTEST\_ABOVE}{Above the client area.}
 462 \twocolitem{wxLIST\_HITTEST\_BELOW}{Below the client area.}
 463 \twocolitem{wxLIST\_HITTEST\_NOWHERE}{In the client area but below the last item.}
 464 \twocolitem{wxLIST\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
 465 \twocolitem{wxLIST\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
 466 \twocolitem{wxLIST\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
 467 \twocolitem{wxLIST\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
 468 \twocolitem{wxLIST\_HITTEST\_TOLEFT}{To the right of the client area.}
 469 \twocolitem{wxLIST\_HITTEST\_TORIGHT}{To the left of the client area.}
 470 \twocolitem{wxLIST\_HITTEST\_ONITEM}{Combination of wxLIST\_HITTEST\_ONITEMICON, wxLIST\_HITTEST\_ONITEMLABEL,
 471 wxLIST\_HITTEST\_ONITEMSTATEICON.}
 472 \end{twocollist}
 473
 474 \pythonnote{A tuple of values is returned in the wxPython version of
 475 this method. The first value is the item id and the second is the
 476 flags value mentioned above.}
 477
 478 \perlnote{In wxPerl this method only takes the {\bf point} parameter
 479   and returns a 2-element list {\tt ( item, flags )}.}
 480
 481 \membersection{wxListCtrl::InsertColumn}\label{wxlistctrlinsertcolumn}
 482
 483 \func{long}{InsertColumn}{\param{long }{col}, \param{wxListItem\& }{info}}
 484
 485 For list view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
 486
 487 \func{long}{InsertColumn}{\param{long }{col}, \param{const wxString\& }{heading}, \param{int }{format = wxLIST\_FORMAT\_LEFT},\rtfsp
 488 \param{int }{width = -1}}
 489
 490 For list view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
 491
 492 \pythonnote{In place of a single overloaded method name, wxPython
 493 implements the following methods:\par
 494 \indented{2cm}{\begin{twocollist}
 495 \twocolitem{{\bf InsertColumn(col, heading, format=wxLIST\_FORMAT\_LEFT,
 496 width=-1)}}{Creates a column using a header string only.}
 497 \twocolitem{{\bf InsertColumnInfo(col, item)}}{Creates a column using a
 498 wxListInfo.}
 499 \end{twocollist}}
 500 }
 501
 502 \membersection{wxListCtrl::InsertItem}\label{wxlistctrlinsertitem}
 503
 504 \func{long}{InsertItem}{\param{wxListItem\& }{info}}
 505
 506 Inserts an item, returning the index of the new item if successful,
 507 -1 otherwise.
 508
 509 \func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}}
 510
 511 Inserts a string item.
 512
 513 \func{long}{InsertItem}{\param{long }{index}, \param{int }{imageIndex}}
 514
 515 Inserts an image item.
 516
 517 \func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}, \param{int }{imageIndex}}
 518
 519 Insert an image/string item.
 520
 521 \wxheading{Parameters}
 522
 523 \docparam{info}{wxListItem object}
 524
 525 \docparam{index}{Index of the new item, supplied by the application}
 526
 527 \docparam{label}{String label}
 528
 529 \docparam{imageIndex}{index into the image list associated with this control and view style}
 530
 531 \pythonnote{In place of a single overloaded method name, wxPython
 532 implements the following methods:\par
 533 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 534 \twocolitem{{\bf InsertItem(item)}}{Inserts an item using a wxListItem.}
 535 \twocolitem{{\bf InsertStringItem(index, label)}}{Inserts a string item.}
 536 \twocolitem{{\bf InsertImageItem(index, imageIndex)}}{Inserts an image item.}
 537 \twocolitem{{\bf InsertImageStringItem(index, label, imageIndex)}}{Insert an image/string item.}
 538 \end{twocollist}}
 539 }
 540
 541 \perlnote{In wxPerl there are four methods instead of a single overloaded
 542 method:\par
 543 \indented{2cm}{\begin{twocollist}
 544 \twocolitem{{\bf InsertItem( item )}}{Inserts a Wx::ListItem}
 545 \twocolitem{{\bf InsertStringItem( index, label )}}{Inserts a string item}
 546 \twocolitem{{\bf InsertImageItem( index, imageIndex )}}{Inserts an image item}
 547 \twocolitem{{\bf InsertImageStringItem( index, label, imageIndex )}}{Inserts
 548  an item with a string and an image}
 549 \end{twocollist}
 550 }}
 551
 552 \membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}
 553
 554 \func{virtual wxListItemAttr *}{OnGetItemAttr}{\param{long }{item}}
 555
 556 This function may be overloaded in the derived class for a control with
 557 {\tt wxLC\_VIRTUAL} style. It should return the attribute for the
 558 for the specified {\tt item} or {\tt NULL} to use the default appearance
 559 parameters.
 560
 561 The base class version always returns {\tt NULL}.
 562
 563 \wxheading{See also}
 564
 565 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
 566 \helpref{OnGetItemText}{wxlistctrlongetitemtext}
 567
 568 \membersection{wxListCtrl::OnGetItemImage}\label{wxlistctrlongetitemimage}
 569
 570 \func{virtual int}{OnGetItemImage}{\param{long }{item}}
 571
 572 This function must be overloaded in the derived class for a control with
 573 {\tt wxLC\_VIRTUAL} style having an \helpref{image list}{wxlistctrlsetimagelist}
 574 (if the control doesn't have an image list, it is not necessary to overload
 575  it). It should return the index of the items image in the controls image list
 576 or $-1$ for no image.
 577
 578 The base class version always returns $-1$.
 579
 580 \wxheading{See also}
 581
 582 \helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
 583 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
 584
 585 \membersection{wxListCtrl::OnGetItemText}\label{wxlistctrlongetitemtext}
 586
 587 \func{virtual wxString}{OnGetItemText}{\param{long }{item}, \param{long }{column}}
 588
 589 This function {\bf must} be overloaded in the derived class for a control with
 590 {\tt wxLC\_VIRTUAL} style. It should return the string containing the text of
 591 the given {\it column} for the specified {\tt item}.
 592
 593 \wxheading{See also}
 594
 595 \helpref{SetItemCount}{wxlistctrlsetitemcount},\\
 596 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
 597 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
 598
 599 \membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}
 600
 601 \func{bool}{ScrollList}{\param{int }{dx}, \param{int }{dy}}
 602
 603 Scrolls the list control. If in icon, small icon or report view mode,
 604 dx specifies the number of pixels to scroll. If in list view mode, dx
 605 specifies the number of columns to scroll.
 606
 607 If in icon, small icon or list view mode, dy specifies the number of pixels
 608 to scroll. If in report view mode, dy specifies the number of lines to scroll.
 609
 610 \membersection{wxListCtrl::SetBackgroundColour}\label{wxlistctrlsetbackgroundcolour}
 611
 612 \func{void}{SetBackgroundColour}{\param{const wxColour\& }{col}}
 613
 614 Sets the background colour (GetBackgroundColour already implicit in
 615 wxWindow class).
 616
 617 \membersection{wxListCtrl::SetColumn}\label{wxlistctrlsetcolumn}
 618
 619 \func{bool}{SetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}
 620
 621 Sets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
 622 information.
 623
 624 \membersection{wxListCtrl::SetColumnWidth}\label{wxlistctrlsetcolumnwidth}
 625
 626 \func{bool}{SetColumnWidth}{\param{int }{col}, \param{int }{width}}
 627
 628 Sets the column width.
 629
 630 {\it width} can be a width in pixels or wxLIST\_AUTOSIZE (-1) or wxLIST\_AUTOSIZE\_USEHEADER (-2).
 631 wxLIST\_AUTOSIZE will resize the column to the length of its longest item. wxLIST\_AUTOSIZE\_USEHEADER
 632 will resize the column to the length of the header (Win32) or 80 pixels (other platforms).
 633
 634 In small or normal icon view, {\it col} must be -1, and the column width is set for all columns.
 635
 636 \membersection{wxListCtrl::SetImageList}\label{wxlistctrlsetimagelist}
 637
 638 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
 639
 640 Sets the image list associated with the control. {\it which} is one of
 641 wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).
 642
 643 This method does not take ownership of the image list, you have to
 644 delete it yourself.
 645
 646 \wxheading{See also}
 647
 648 \helpref{wxListCtrl::AssignImageList}{wxlistctrlassignimagelist}
 649
 650
 651 \membersection{wxListCtrl::SetItem}\label{wxlistctrlsetitem}
 652
 653 \func{bool}{SetItem}{\param{wxListItem\& }{info}}
 654
 655 \func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const }{wxString\& label}, \param{int }{imageId = -1}}
 656
 657 Sets information about the item.
 658
 659 wxListItem is a class with the following members:
 660
 661 \twocolwidtha{5cm}
 662 \begin{twocollist}\itemsep=0pt
 663 \twocolitem{long m\_mask}{Indicates which fields are valid. See the list of valid mask flags below.}
 664 \twocolitem{long m\_itemId}{The zero-based item position.}
 665 \twocolitem{int m\_col}{Zero-based column, if in report mode.}
 666 \twocolitem{long m\_state}{The state of the item. See the list of valid state flags below.}
 667 \twocolitem{long m\_stateMask}{A mask indicating which state flags are valid. See the list of valid state flags below.}
 668 \twocolitem{wxString m\_text}{The label/header text.}
 669 \twocolitem{int m\_image}{The zero-based index into an image list.}
 670 \twocolitem{long m\_data}{Application-defined data.}
 671 \twocolitem{int m\_format}{For columns only: the format. Can be wxLIST\_FORMAT\_LEFT, wxLIST\_FORMAT\_RIGHT or
 672 wxLIST\_FORMAT\_CENTRE.}
 673 \twocolitem{int m\_width}{For columns only: the column width.}
 674 \end{twocollist}
 675
 676 The {\bf m\_mask} member contains a bitlist specifying which of the other fields are valid. The flags are:
 677
 678 \twocolwidtha{5cm}
 679 \begin{twocollist}\itemsep=0pt
 680 \twocolitem{wxLIST\_MASK\_STATE}{The {\bf m\_state} field is valid.}
 681 \twocolitem{wxLIST\_MASK\_TEXT}{The {\bf m\_text} field is valid.}
 682 \twocolitem{wxLIST\_MASK\_IMAGE}{The {\bf m\_image} field is valid.}
 683 \twocolitem{wxLIST\_MASK\_DATA}{The {\bf m\_data} field is valid.}
 684 \twocolitem{wxLIST\_MASK\_WIDTH}{The {\bf m\_width} field is valid.}
 685 \twocolitem{wxLIST\_MASK\_FORMAT}{The {\bf m\_format} field is valid.}
 686 \end{twocollist}
 687
 688 The {\bf m\_stateMask} and {\bf m\_state} members take flags from the following:
 689
 690 The wxListItem object can also contain item-specific colour and font
 691 information: for this you need to call one of SetTextColour(),
 692 SetBackgroundColour() or SetFont() functions on it passing it the colour/font
 693 to use. If the colour/font is not specified, the default list control
 694 colour/font is used.
 695
 696 \twocolwidtha{5cm}
 697 \begin{twocollist}\itemsep=0pt
 698 \twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is. Win32 only. }
 699 \twocolitem{wxLIST\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event. Win32 only. }
 700 \twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
 701 \twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
 702 \twocolitem{wxLIST\_STATE\_CUT}{The item is in the cut state. Win32 only. }
 703 \end{twocollist}
 704
 705 \func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const wxString\& }{label}, \param{int }{imageId = -1}}
 706
 707 Sets a string field at a particular column.
 708
 709 \pythonnote{In place of a single overloaded method name, wxPython
 710 implements the following methods:\par
 711 \indented{2cm}{\begin{twocollist}
 712 \twocolitem{{\bf SetItem(item)}}{Sets information about the given wxListItem.}
 713 \twocolitem{{\bf SetStringItem(index, col, label, imageId)}}{Sets a
 714 string or image at a given location.}
 715 \end{twocollist}}
 716 }
 717
 718 \membersection{wxListCtrl::SetItemCount}\label{wxlistctrlsetitemcount}
 719
 720 \func{void}{SetItemCount}{\param{long }{count}}
 721
 722 This method can only be used with virtual list controls. It is used to indicate
 723 to the control the number of items it contains. After calling it, the main
 724 program should be ready to handle calls to various item callbacks (such as
 725 \helpref{OnGetItemText}{wxlistctrlongetitemtext}) for all vitems in the range
 726 from $0$ to {\it count}.
 727
 728 \membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}
 729
 730 \func{bool}{SetItemData}{\param{long }{item}, \param{long }{data}}
 731
 732 Associates application-defined data with this item.
 733
 734 \membersection{wxListCtrl::SetItemImage}\label{wxlistctrlsetitemimage}
 735
 736 \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}, \param{int }{selImage}}
 737
 738 Sets the unselected and selected images associated with the item. The images are indices into the
 739 image list associated with the list control.
 740
 741 \membersection{wxListCtrl::SetItemPosition}\label{wxlistctrlsetitemposition}
 742
 743 \func{bool}{SetItemPosition}{\param{long }{item}, \param{const wxPoint\& }{pos}}
 744
 745 Sets the position of the item, in icon or small icon view.
 746
 747 \membersection{wxListCtrl::SetItemState}\label{wxlistctrlsetitemstate}
 748
 749 \func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}}
 750
 751 Sets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
 752
 753 The {\bf stateMask} indicates which state flags are valid.
 754
 755 \membersection{wxListCtrl::SetItemText}\label{wxlistctrlsetitemtext}
 756
 757 \func{void}{SetItemText}{\param{long }{item}, \param{const wxString\& }{text}}
 758
 759 Sets the item text for this item.
 760
 761 \membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle}
 762
 763 \func{void}{SetSingleStyle}{\param{long }{style}, \param{const bool }{add = TRUE}}
 764
 765 Adds or removes a single window style.
 766
 767 \membersection{wxListCtrl::SetTextColour}\label{wxlistctrlsettextcolour}
 768
 769 \func{void}{SetTextColour}{\param{const wxColour\& }{col}}
 770
 771 Sets the text colour of the list control.
 772
 773 \membersection{wxListCtrl::SetWindowStyleFlag}\label{wxlistctrlsetwindowstyleflag}
 774
 775 \func{void}{SetWindowStyleFlag}{\param{long }{style}}
 776
 777 Sets the whole window style.
 778
 779 \membersection{wxListCtrl::SortItems}\label{wxlistctrlsortitems}
 780
 781 \func{bool}{SortItems}{\param{wxListCtrlCompare }{fnSortCallBack}, \param{long }{data}}
 782
 783 Call this function to sort the items in the list control. Sorting is done
 784 using the specified {\it fnSortCallBack} function. This function must have the
 785 following prototype:
 786
 787 \begin{verbatim}
 788 int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
 789 \end{verbatim}
 790
 791 It is called each time when the two items must be compared and should return 0
 792 if the items are equal, negative value if the first item is less than the
 793 second one and positive value if the first one is greater than the second one
 794 (the same convention as used by {\tt qsort(3)}).
 795
 796 \wxheading{Parameters}
 797
 798 \docparam{item1}{client data associated with the first item ({\bf NOT} the index).}
 799
 800 \docparam{item2}{client data associated with the second item ({\bf NOT} the index).}
 801
 802 \docparam{data}{the value passed to SortItems() itself.}
 803
 804 Notice that the control may only be sorted on client data associated with the
 805 items, so you {\bf must} use \helpref{SetItemData}{wxlistctrlsetitemdata} if
 806 you want to be able to sort the items in the control.
 807
 808 Please see the \helpref{listctrl sample}{samplelistctrl} for an example of
 809 using this function.
 810
 811 \pythonnote{wxPython uses the sortData parameter to pass the Python
 812 function to call, so it is not available for programmer use.  Call
 813 SortItems with a reference to a callable object that expects two
 814 parameters.}
 815
 816 \perlnote{In wxPerl the comparison function must take just two parameters;
 817  however, you may use a closure to achieve an effect similar to the
 818  SortItems third parameter.}
 819