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