interface/wx/listctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/listctrl.h
   3 // Purpose:     interface of wxListCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxListCtrl
  11
  12     A list control presents lists in a number of formats: list view, report view,
  13     icon view and small icon view. In any case, elements are numbered from zero.
  14     For all these modes, the items are stored in the control and must be added to
  15     it using wxListCtrl::InsertItem method.
  16
  17     A special case of report view quite different from the other modes of the list
  18     control is a virtual control in which the items data (including text, images
  19     and attributes) is managed by the main program and is requested by the control
  20     itself only when needed which allows to have controls with millions of items
  21     without consuming much memory. To use virtual list control you must use
  22     wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText
  23     (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
  24     wxListCtrl::OnGetItemAttr) to return the information about the items when the
  25     control requests it.
  26
  27     Virtual list control can be used as a normal one except that no operations
  28     which can take time proportional to the number of items in the control happen
  29     -- this is required to allow having a practically infinite number of items.
  30     For example, in a multiple selection virtual list control, the selections won't
  31     be sent when many items are selected at once because this could mean iterating
  32     over all the items.
  33
  34     Using many of wxListCtrl features is shown in the
  35     @ref page_samples_listctrl "corresponding sample".
  36
  37     To intercept events from a list control, use the event table macros described
  38     in wxListEvent.
  39
  40     <b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native
  41     implementation for report mode, and uses a generic implementation for other
  42     modes. You can use the generic implementation for report mode as well by setting
  43     the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1.
  44
  45
  46     @beginStyleTable
  47     @style{wxLC_LIST}
  48            Multicolumn list view, with optional small icons. Columns are
  49            computed automatically, i.e. you don't set columns as in
  50            @c wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
  51     @style{wxLC_REPORT}
  52            Single or multicolumn report view, with optional header.
  53     @style{wxLC_VIRTUAL}
  54            The application provides items text on demand. May only be used
  55            with @c wxLC_REPORT.
  56     @style{wxLC_ICON}
  57            Large icon view, with optional labels.
  58     @style{wxLC_SMALL_ICON}
  59            Small icon view, with optional labels.
  60     @style{wxLC_ALIGN_TOP}
  61            Icons align to the top. Win32 default, Win32 only.
  62     @style{wxLC_ALIGN_LEFT}
  63            Icons align to the left.
  64     @style{wxLC_AUTOARRANGE}
  65            Icons arrange themselves. Win32 only.
  66     @style{wxLC_EDIT_LABELS}
  67            Labels are editable: the application will be notified when editing
  68            starts.
  69     @style{wxLC_NO_HEADER}
  70            No header in report mode.
  71     @style{wxLC_SINGLE_SEL}
  72            Single selection (default is multiple).
  73     @style{wxLC_SORT_ASCENDING}
  74            Sort in ascending order. (You must still supply a comparison callback
  75            in wxListCtrl::SortItems.)
  76     @style{wxLC_SORT_DESCENDING}
  77            Sort in descending order. (You must still supply a comparison callback
  78            in wxListCtrl::SortItems.)
  79     @style{wxLC_HRULES}
  80            Draws light horizontal rules between rows in report mode.
  81     @style{wxLC_VRULES}
  82            Draws light vertical rules between columns in report mode.
  83     @endStyleTable
  84
  85
  86     @beginEventEmissionTable{wxListEvent}
  87     @event{EVT_LIST_BEGIN_DRAG(id, func)}
  88            Begin dragging with the left mouse button.
  89           Processes a @c wxEVT_COMMAND_LIST_BEGIN_DRAG event type.
  90     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
  91            Begin dragging with the right mouse button.
  92            Processes a @c wxEVT_COMMAND_LIST_BEGIN_RDRAG event type.
  93     @event{EVT_BEGIN_LABEL_EDIT(id, func)}
  94            Begin editing a label. This can be prevented by calling Veto().
  95            Processes a @c wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT event type.
  96     @event{EVT_LIST_END_LABEL_EDIT(id, func)}
  97            Finish editing a label. This can be prevented by calling Veto().
  98            Processes a @c wxEVT_COMMAND_LIST_END_LABEL_EDIT event type.
  99     @event{EVT_LIST_DELETE_ITEM(id, func)}
 100            An item was deleted.
 101            Processes a @c wxEVT_COMMAND_LIST_DELETE_ITEM event type.
 102     @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
 103            All items were deleted.
 104            Processes a @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event type.
 105     @event{EVT_LIST_ITEM_SELECTED(id, func)}
 106            The item has been selected.
 107            Processes a @c wxEVT_COMMAND_LIST_ITEM_SELECTED event type.
 108     @event{EVT_LIST_ITEM_DESELECTED(id, func)}
 109            The item has been deselected.
 110            Processes a @c wxEVT_COMMAND_LIST_ITEM_DESELECTED event type.
 111     @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
 112            The item has been activated (ENTER or double click).
 113            Processes a @c wxEVT_COMMAND_LIST_ITEM_ACTIVATED event type.
 114     @event{EVT_LIST_ITEM_FOCUSED(id, func)}
 115            The currently focused item has changed.
 116            Processes a @c wxEVT_COMMAND_LIST_ITEM_FOCUSED event type.
 117     @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
 118            The middle mouse button has been clicked on an item. This is
 119            only supported by the generic control.
 120            Processes a @c wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK event type.
 121     @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
 122           The right mouse button has been clicked on an item.
 123           Processes a @c wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK event type.
 124     @event{EVT_LIST_KEY_DOWN(id, func)}
 125            A key has been pressed.
 126            Processes a @c wxEVT_COMMAND_LIST_KEY_DOWN event type.
 127     @event{EVT_LIST_INSERT_ITEM(id, func)}
 128            An item has been inserted.
 129            Processes a @c wxEVT_COMMAND_LIST_INSERT_ITEM event type.
 130     @event{EVT_LIST_COL_CLICK(id, func)}
 131            A column (m_col) has been left-clicked.
 132            Processes a @c wxEVT_COMMAND_LIST_COL_CLICK event type.
 133     @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
 134            A column (m_col) has been right-clicked.
 135            Processes a @c wxEVT_COMMAND_LIST_COL_RIGHT_CLICK event type.
 136     @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
 137            The user started resizing a column - can be vetoed.
 138            Processes a @c wxEVT_COMMAND_LIST_COL_BEGIN_DRAG event type.
 139     @event{EVT_LIST_COL_DRAGGING(id, func)}
 140            The divider between columns is being dragged.
 141            Processes a @c wxEVT_COMMAND_LIST_COL_DRAGGING event type.
 142     @event{EVT_LIST_COL_END_DRAG(id, func)}
 143            A column has been resized by the user.
 144            Processes a @c wxEVT_COMMAND_LIST_COL_END_DRAG event type.
 145     @event{EVT_LIST_CACHE_HINT(id, func)}
 146            Prepare cache for a virtual list control.
 147            Processes a @c wxEVT_COMMAND_LIST_CACHE_HINT event type.
 148     @endEventTable
 149
 150
 151     @library{wxcore}
 152     @category{ctrl}
 153     @appearance{listctrl.png}
 154
 155     @see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList,
 156          wxListEvent, wxListItem, wxEditableListBox
 157 */
 158 class wxListCtrl : public wxControl
 159 {
 160 public:
 161     /**
 162        Default constructor.
 163     */
 164     wxListCtrl();
 165
 166     /**
 167         Constructor, creating and showing a list control.
 168
 169         @param parent
 170             Parent window. Must not be @NULL.
 171         @param id
 172             Window identifier. The value wxID_ANY indicates a default value.
 173         @param pos
 174             Window position.
 175             If ::wxDefaultPosition is specified then a default position is chosen.
 176         @param size
 177             Window size.
 178             If ::wxDefaultSize is specified then the window is sized appropriately.
 179         @param style
 180             Window style. See wxListCtrl.
 181         @param validator
 182             Window validator.
 183         @param name
 184             Window name.
 185
 186         @see Create(), wxValidator
 187     */
 188     wxListCtrl(wxWindow* parent, wxWindowID id,
 189                const wxPoint& pos = wxDefaultPosition,
 190                const wxSize& size = wxDefaultSize,
 191                long style = wxLC_ICON,
 192                const wxValidator& validator = wxDefaultValidator,
 193                const wxString& name = wxListCtrlNameStr);
 194
 195     /**
 196         Destructor, destroying the list control.
 197     */
 198     virtual ~wxListCtrl();
 199
 200     /**
 201         Arranges the items in icon or small icon view.
 202         This only has effect on Win32. @a flag is one of:
 203         - wxLIST_ALIGN_DEFAULT: Default alignment.
 204         - wxLIST_ALIGN_LEFT: Align to the left side of the control.
 205         - wxLIST_ALIGN_TOP: Align to the top side of the control.
 206         - wxLIST_ALIGN_SNAP_TO_GRID: Snap to grid.
 207     */
 208     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 209
 210     /**
 211         Sets the image list associated with the control and takes ownership of it
 212         (i.e. the control will, unlike when using SetImageList(), delete the list
 213         when destroyed). @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
 214         @c wxIMAGE_LIST_STATE (the last is unimplemented).
 215
 216         @see SetImageList()
 217     */
 218     void AssignImageList(wxImageList* imageList, int which);
 219
 220     /**
 221         Deletes all items and all columns.
 222
 223         @note  This sends an event of type @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS
 224                under all platforms.
 225     */
 226     void ClearAll();
 227
 228     /**
 229         Creates the list control. See wxListCtrl() for further details.
 230     */
 231     bool Create(wxWindow* parent, wxWindowID id,
 232                 const wxPoint& pos = wxDefaultPosition,
 233                 const wxSize& size = wxDefaultSize,
 234                 long style = wxLC_ICON,
 235                 const wxValidator& validator = wxDefaultValidator,
 236                 const wxString& name = wxListCtrlNameStr);
 237
 238     /**
 239         Deletes all items in the list control.
 240
 241         This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM
 242         event because deleting many items from the control would be too slow
 243         then (unlike wxListCtrl::DeleteItem) but it does send the special @c
 244         wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event if the control was not empty.
 245         If it was already empty, nothing is done and no event is sent.
 246
 247         @return @true if the items were successfully deleted or if the control
 248             was already empty, @false if an error occurred while deleting the
 249             items.
 250     */
 251     bool DeleteAllItems();
 252
 253     /**
 254         Deletes a column.
 255     */
 256     bool DeleteColumn(int col);
 257
 258     /**
 259         Deletes the specified item.
 260         This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the
 261         item being deleted.
 262
 263         @see DeleteAllItems()
 264     */
 265     bool DeleteItem(long item);
 266
 267     /**
 268         Starts editing the label of the given item.
 269
 270         This function generates a @c EVT_LIST_BEGIN_LABEL_EDIT event which can be
 271         vetoed so that no text control will appear for in-place editing.
 272
 273         If the user changed the label (i.e. s/he does not press ESC or leave
 274         the text control without changes, a @c EVT_LIST_END_LABEL_EDIT event
 275         will be sent which can be vetoed as well.
 276     */
 277     wxTextCtrl* EditLabel(long item,
 278                           wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl));
 279
 280     /**
 281         Finish editing the label.
 282
 283         This method allows to programmatically end editing a list control item
 284         in place. Usually it will only be called when editing is in progress,
 285         i.e. if GetEditControl() returns non-NULL. In particular, do not call
 286         it from EVT_LIST_BEGIN_LABEL_EDIT handler as the edit control is not
 287         yet fully created by then, just veto the event in this handler instead
 288         to prevent the editing from even starting.
 289
 290         Notice that calling this method will result in EVT_LIST_END_LABEL_EDIT
 291         event being generated.
 292
 293         Currently only implemented in wxMSW.
 294
 295         @param cancel If @true, discard the changes made by user, as if @c
 296             Escape key was pressed. Otherwise, accept the changes as if @c
 297             Return was pressed.
 298         @return @true if item editing wad finished or @false if no item as
 299             being edited.
 300      */
 301     bool EndEditLabel(bool cancel);
 302
 303     /**
 304         Ensures this item is visible.
 305     */
 306     bool EnsureVisible(long item);
 307
 308     /**
 309         Find an item whose label matches this string, starting from start or the
 310         beginning if start is @c -1. The string comparison is case insensitive.
 311
 312         If @a partial is @true then this method will look for items which begin with @a str.
 313
 314         @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
 315     */
 316     long FindItem(long start, const wxString& str,
 317                   bool partial = false);
 318
 319     /**
 320         Find an item whose data matches this data, starting from start or the
 321         beginning if 'start' is @c -1.
 322
 323         @beginWxPerlOnly
 324         In wxPerl this method is implemented as FindItemData(start, data).
 325         @endWxPerlOnly
 326
 327         @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
 328     */
 329     long FindItem(long start, wxUIntPtr data);
 330
 331     /**
 332         Find an item nearest this position in the specified direction,
 333         starting from @a start or the beginning if @a start is -1.
 334
 335         @beginWxPerlOnly
 336         In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
 337         @endWxPerlOnly
 338
 339         @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
 340     */
 341     long FindItem(long start, const wxPoint& pt, int direction);
 342
 343     /**
 344         Gets information about this column.
 345         See SetItem() for more information.
 346
 347         @beginWxPerlOnly
 348         In wxPerl this method takes only the @a col parameter and
 349         returns a @c Wx::ListItem (or @c undef).
 350         @endWxPerlOnly
 351     */
 352     bool GetColumn(int col, wxListItem& item) const;
 353
 354     /**
 355         Returns the number of columns.
 356     */
 357     int GetColumnCount() const;
 358
 359     /**
 360         Gets the column index from its position in visual order.
 361
 362         After calling SetColumnsOrder(), the index returned by this function
 363         corresponds to the value of the element number @a pos in the array
 364         returned by GetColumnsOrder().
 365
 366         Please see SetColumnsOrder() documentation for an example and
 367         additional remarks about the columns ordering.
 368
 369         @see GetColumnOrder()
 370     */
 371     int GetColumnIndexFromOrder(int pos) const;
 372
 373     /**
 374         Gets the column visual order position.
 375
 376         This function returns the index of the column which appears at the
 377         given visual position, e.g. calling it with @a col equal to 0 returns
 378         the index of the first shown column.
 379
 380         Please see SetColumnsOrder() documentation for an example and
 381         additional remarks about the columns ordering.
 382
 383         @see GetColumnsOrder(), GetColumnIndexFromOrder()
 384     */
 385     int GetColumnOrder(int col) const;
 386
 387     /**
 388         Gets the column width (report view only).
 389     */
 390     int GetColumnWidth(int col) const;
 391
 392     /**
 393         Returns the array containing the orders of all columns.
 394
 395         On error, an empty array is returned.
 396
 397         Please see SetColumnsOrder() documentation for an example and
 398         additional remarks about the columns ordering.
 399
 400         @see GetColumnOrder(), GetColumnIndexFromOrder()
 401     */
 402     wxArrayInt GetColumnsOrder() const;
 403
 404     /**
 405         Gets the number of items that can fit vertically in the visible area of
 406         the list control (list or report view) or the total number of items in
 407         the list control (icon or small icon view).
 408     */
 409     int GetCountPerPage() const;
 410
 411     /**
 412         Returns the edit control being currently used to edit a label.
 413         Returns @NULL if no label is being edited.
 414
 415         @note It is currently only implemented for wxMSW and the generic version,
 416               not for the native Mac OS X version.
 417     */
 418     wxTextCtrl* GetEditControl() const;
 419
 420     /**
 421         Returns the specified image list. @a which may be one of:
 422         - wxIMAGE_LIST_NORMAL: The normal (large icon) image list.
 423         - wxIMAGE_LIST_SMALL: The small icon image list.
 424         - wxIMAGE_LIST_STATE: The user-defined state image list (unimplemented).
 425     */
 426     wxImageList* GetImageList(int which) const;
 427
 428     /**
 429         Gets information about the item. See SetItem() for more information.
 430
 431         You must call @e info.SetId() to set the ID of item you're interested in
 432         before calling this method, and @e info.SetMask() with the flags indicating
 433         what fields you need to retrieve from @a info.
 434
 435         @beginWxPerlOnly
 436         In wxPerl this method takes as parameter the ID of the item
 437         and (optionally) the column, and returns a Wx::ListItem object.
 438         @endWxPerlOnly
 439     */
 440     bool GetItem(wxListItem& info) const;
 441
 442     /**
 443         Returns the colour for this item.
 444         If the item has no specific colour, returns an invalid colour
 445         (and not the default background control of the control itself).
 446
 447         @see GetItemTextColour()
 448     */
 449     wxColour GetItemBackgroundColour(long item) const;
 450
 451     /**
 452         Returns the number of items in the list control.
 453     */
 454     int GetItemCount() const;
 455
 456     /**
 457         Gets the application-defined data associated with this item.
 458     */
 459     wxUIntPtr GetItemData(long item) const;
 460
 461     /**
 462         Returns the item's font.
 463     */
 464     wxFont GetItemFont(long item) const;
 465
 466     /**
 467         Returns the position of the item, in icon or small icon view.
 468
 469         @beginWxPerlOnly
 470         In wxPerl this method takes only the @a item parameter and
 471         returns a @c Wx::Point (or @c undef).
 472         @endWxPerlOnly
 473     */
 474     bool GetItemPosition(long item, wxPoint& pos) const;
 475
 476     /**
 477         Returns the rectangle representing the item's size and position, in physical
 478         coordinates.
 479
 480         @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
 481
 482         @beginWxPerlOnly
 483         In wxPerl this method takes only the @a item and @a code parameters and
 484         returns a @c Wx::Rect (or @c undef).
 485         @endWxPerlOnly
 486     */
 487     bool GetItemRect(long item, wxRect& rect,
 488                      int code = wxLIST_RECT_BOUNDS) const;
 489
 490     /**
 491         Retrieves the spacing between icons in pixels: horizontal spacing is
 492         returned as @c x component of the wxSize object and the vertical spacing
 493         as its @c y component.
 494     */
 495     wxSize GetItemSpacing() const;
 496
 497     /**
 498         Gets the item state. For a list of state flags, see SetItem().
 499         The @a stateMask indicates which state flags are of interest.
 500     */
 501     int GetItemState(long item, long stateMask) const;
 502
 503     /**
 504         Gets the item text for this item.
 505
 506         @param item
 507             Item (zero-based) index.
 508         @param col
 509             Item column (zero-based) index. Column 0 is the default. This
 510             parameter is new in wxWidgets 2.9.1.
 511     */
 512     wxString GetItemText(long item, int col = 0) const;
 513
 514     /**
 515         Returns the colour for this item.
 516
 517         If the item has no specific colour, returns an invalid colour (and not the
 518         default foreground control of the control itself as this wouldn't allow
 519         distinguishing between items having the same colour as the current control
 520         foreground and items with default colour which, hence, have always the
 521         same colour as the control).
 522     */
 523     wxColour GetItemTextColour(long item) const;
 524
 525     /**
 526         Searches for an item with the given geometry or state, starting from
 527         @a item but excluding the @a item itself.
 528
 529         If @a item is -1, the first item that matches the specified flags will be returned.
 530         Returns the first item with given state following @a item or -1 if no such item found.
 531         This function may be used to find all selected items in the control like this:
 532
 533         @code
 534         long item = -1;
 535         for ( ;; )
 536         {
 537             item = listctrl->GetNextItem(item,
 538                                         wxLIST_NEXT_ALL,
 539                                         wxLIST_STATE_SELECTED);
 540             if ( item == -1 )
 541                 break;
 542
 543             // this item is selected - do whatever is needed with it
 544             wxLogMessage("Item %ld is selected.", item);
 545         }
 546         @endcode
 547
 548         @a geometry can be one of:
 549         - wxLIST_NEXT_ABOVE: Searches for an item above the specified item.
 550         - wxLIST_NEXT_ALL: Searches for subsequent item by index.
 551         - wxLIST_NEXT_BELOW: Searches for an item below the specified item.
 552         - wxLIST_NEXT_LEFT: Searches for an item to the left of the specified item.
 553         - wxLIST_NEXT_RIGHT: Searches for an item to the right of the specified item.
 554
 555         @note this parameter is only supported by wxMSW currently and ignored on
 556               other platforms.
 557
 558         @a state can be a bitlist of the following:
 559         - wxLIST_STATE_DONTCARE: Don't care what the state is.
 560         - wxLIST_STATE_DROPHILITED: The item indicates it is a drop target.
 561         - wxLIST_STATE_FOCUSED: The item has the focus.
 562         - wxLIST_STATE_SELECTED: The item is selected.
 563         - wxLIST_STATE_CUT: The item is selected as part of a cut and paste operation.
 564     */
 565     long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL,
 566                      int state = wxLIST_STATE_DONTCARE) const;
 567
 568     /**
 569         Returns the number of selected items in the list control.
 570     */
 571     int GetSelectedItemCount() const;
 572
 573     /**
 574         Returns the rectangle representing the size and position, in physical
 575         coordinates, of the given subitem, i.e. the part of the row @a item in the
 576         column @a subItem.
 577
 578         This method is only meaningful when the wxListCtrl is in the report mode.
 579         If @a subItem parameter is equal to the special value
 580         @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
 581         for GetItemRect().
 582
 583         @a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or
 584         @c wxLIST_RECT_LABEL.
 585
 586         @since 2.7.0
 587     */
 588     bool GetSubItemRect(long item, long subItem, wxRect& rect,
 589                         int code = wxLIST_RECT_BOUNDS) const;
 590
 591     /**
 592         Gets the text colour of the list control.
 593     */
 594     wxColour GetTextColour() const;
 595
 596     /**
 597         Gets the index of the topmost visible item when in list or report view.
 598     */
 599     long GetTopItem() const;
 600
 601     /**
 602         Returns the rectangle taken by all items in the control. In other words, if the
 603         controls client size were equal to the size of this rectangle, no scrollbars
 604         would be needed and no free space would be left.
 605
 606         Note that this function only works in the icon and small icon views, not in
 607         list or report views (this is a limitation of the native Win32 control).
 608     */
 609     wxRect GetViewRect() const;
 610
 611     /**
 612         Determines which item (if any) is at the specified point, giving details
 613         in @a flags. Returns index of the item or @c wxNOT_FOUND if no item is at
 614         the specified point.
 615
 616         @a flags will be a combination of the following flags:
 617         - wxLIST_HITTEST_ABOVE: Above the client area.
 618         - wxLIST_HITTEST_BELOW: Below the client area.
 619         - wxLIST_HITTEST_NOWHERE: In the client area but below the last item.
 620         - wxLIST_HITTEST_ONITEMICON: On the bitmap associated with an item.
 621         - wxLIST_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
 622         - wxLIST_HITTEST_ONITEMRIGHT: In the area to the right of an item.
 623         - wxLIST_HITTEST_ONITEMSTATEICON: On the state icon for a tree view item
 624           that is in a user-defined state.
 625         - wxLIST_HITTEST_TOLEFT: To the right of the client area.
 626         - wxLIST_HITTEST_TORIGHT: To the left of the client area.
 627         - wxLIST_HITTEST_ONITEM: Combination of @c wxLIST_HITTEST_ONITEMICON,
 628           @c wxLIST_HITTEST_ONITEMLABEL, @c wxLIST_HITTEST_ONITEMSTATEICON.
 629
 630         If @a ptrSubItem is not @NULL and the wxListCtrl is in the report
 631         mode the subitem (or column) number will also be provided.
 632         This feature is only available in version 2.7.0 or higher and is currently only
 633         implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on
 634         the host system or the value stored in @a ptrSubItem will be always -1.
 635         To compile this feature into wxWidgets library you need to have access to
 636         commctrl.h of version 4.70 that is provided by Microsoft.
 637
 638         @beginWxPerlOnly
 639         In wxPerl this method only takes the @a point parameter
 640         and returns a 2-element list (item, flags).
 641         @endWxPerlOnly
 642     */
 643     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 644
 645     /**
 646         Returns true if the control is currently using ::wxLC_REPORT style.
 647      */
 648     bool InReportView() const;
 649
 650     /**
 651         For report view mode (only), inserts a column. For more details, see SetItem().
 652     */
 653     long InsertColumn(long col, wxListItem& info);
 654
 655     /**
 656         For report view mode (only), inserts a column. For more details, see SetItem().
 657     */
 658     long InsertColumn(long col, const wxString& heading,
 659                       int format = wxLIST_FORMAT_LEFT,
 660                       int width = -1);
 661
 662     /**
 663         Inserts an item, returning the index of the new item if successful, -1 otherwise.
 664
 665         @param info
 666             wxListItem object
 667     */
 668     long InsertItem(wxListItem& info);
 669
 670     /**
 671         Insert an string item.
 672
 673         @param index
 674             Index of the new item, supplied by the application
 675         @param label
 676             String label
 677
 678         @beginWxPerlOnly
 679         In wxPerl this method is implemented as InsertStringItem(index, label).
 680         @endWxPerlOnly
 681     */
 682     long InsertItem(long index, const wxString& label);
 683
 684     /**
 685         Insert an image item.
 686
 687         @param index
 688             Index of the new item, supplied by the application
 689         @param imageIndex
 690             Index into the image list associated with this control and view style
 691
 692         @beginWxPerlOnly
 693         In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
 694         @endWxPerlOnly
 695     */
 696     long InsertItem(long index, int imageIndex);
 697
 698     /**
 699         Insert an image/string item.
 700
 701         @param index
 702             Index of the new item, supplied by the application
 703         @param label
 704             String label
 705         @param imageIndex
 706             Index into the image list associated with this control and view style
 707
 708         @beginWxPerlOnly
 709         In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
 710         @endWxPerlOnly
 711     */
 712     long InsertItem(long index, const wxString& label,
 713                     int imageIndex);
 714
 715     /**
 716         Returns true if the control is currently in virtual report view.
 717      */
 718     bool IsVirtual() const;
 719
 720     /**
 721         Redraws the given @e item.
 722
 723         This is only useful for the virtual list controls as without calling this
 724         function the displayed value of the item doesn't change even when the
 725         underlying data does change.
 726
 727         @see RefreshItems()
 728     */
 729     void RefreshItem(long item);
 730
 731     /**
 732         Redraws the items between @a itemFrom and @e itemTo.
 733         The starting item must be less than or equal to the ending one.
 734
 735         Just as RefreshItem() this is only useful for virtual list controls.
 736     */
 737     void RefreshItems(long itemFrom, long itemTo);
 738
 739     /**
 740         Scrolls the list control. If in icon, small icon or report view mode,
 741         @a dx specifies the number of pixels to scroll. If in list view mode,
 742         @a dx specifies the number of columns to scroll. @a dy always specifies
 743         the number of pixels to scroll vertically.
 744
 745         @note This method is currently only implemented in the Windows version.
 746     */
 747     bool ScrollList(int dx, int dy);
 748
 749     /**
 750         Sets the background colour.
 751
 752         Note that the wxWindow::GetBackgroundColour() function of wxWindow base
 753         class can be used to retrieve the current background colour.
 754     */
 755     virtual bool SetBackgroundColour(const wxColour& col);
 756
 757     /**
 758         Sets information about this column.
 759         See SetItem() for more information.
 760     */
 761     bool SetColumn(int col, wxListItem& item);
 762
 763     /**
 764         Sets the column width.
 765
 766         @a width can be a width in pixels or @c wxLIST_AUTOSIZE (-1) or
 767         @c wxLIST_AUTOSIZE_USEHEADER (-2).
 768
 769         @c wxLIST_AUTOSIZE will resize the column to the length of its longest item.
 770
 771         @c wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the
 772         header (Win32) or 80 pixels (other platforms).
 773
 774         In small or normal icon view, @a col must be -1, and the column width is set
 775         for all columns.
 776     */
 777     bool SetColumnWidth(int col, int width);
 778
 779     /**
 780         Changes the order in which the columns are shown.
 781
 782         By default, the columns of a list control appear on the screen in order
 783         of their indices, i.e. the column 0 appears first, the column 1 next
 784         and so on. However by using this function it is possible to arbitrarily
 785         reorder the columns visual order and the user can also rearrange the
 786         columns interactively by dragging them. In this case, the index of the
 787         column is not the same as its order and the functions GetColumnOrder()
 788         and GetColumnIndexFromOrder() should be used to translate between them.
 789         Notice that all the other functions still work with the column indices,
 790         i.e. the visual positioning of the columns on screen doesn't affect the
 791         code setting or getting their values for example.
 792
 793         The @a orders array must have the same number elements as the number of
 794         columns and contain each position exactly once. Its n-th element
 795         contains the index of the column to be shown in n-th position, so for a
 796         control with three columns passing an array with elements 2, 0 and 1
 797         results in the third column being displayed first, the first one next
 798         and the second one last.
 799
 800         Example of using it:
 801         @code
 802             wxListCtrl *list = new wxListCtrl(...);
 803             for ( int i = 0; i < 3; i++ )
 804                 list->InsertColumn(i, wxString::Format("Column %d", i));
 805
 806             wxArrayInt order(3);
 807             order[0] = 2;
 808             order[1] = 0;
 809             order[2] = 1;
 810             list->SetColumnsOrder(order);
 811
 812             // now list->GetColumnsOrder() will return order and
 813             // list->GetColumnIndexFromOrder(n) will return order[n] and
 814             // list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
 815             // 1 and 2 respectively
 816         @endcode
 817
 818         Please notice that this function makes sense for report view only and
 819         currently is only implemented in wxMSW port. To avoid explicit tests
 820         for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER
 821         as this will allow it to start working under the other platforms when
 822         support for the column reordering is added there.
 823
 824         @see GetColumnsOrder()
 825     */
 826     bool SetColumnsOrder(const wxArrayInt& orders) const;
 827
 828     /**
 829         Sets the image list associated with the control.
 830
 831         @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
 832         @c wxIMAGE_LIST_STATE (the last is unimplemented).
 833
 834         This method does not take ownership of the image list, you have to
 835         delete it yourself.
 836
 837         @see AssignImageList()
 838     */
 839     void SetImageList(wxImageList* imageList, int which);
 840
 841     /**
 842         Sets the data of an item.
 843
 844         Using the wxListItem's mask and state mask, you can change only selected
 845         attributes of a wxListCtrl item.
 846     */
 847     bool SetItem(wxListItem& info);
 848
 849     /**
 850         Sets an item string field at a particular column.
 851     */
 852     long SetItem(long index, int column, const wxString& label, int imageId = -1);
 853
 854     /**
 855         Sets the background colour for this item.
 856         This function only works in report view mode.
 857         The colour can be retrieved using GetItemBackgroundColour().
 858     */
 859     void SetItemBackgroundColour(long item, const wxColour& col);
 860
 861     /**
 862         Sets the image associated with the item.
 863         In report view, you can specify the column.
 864         The image is an index into the image list associated with the list control.
 865     */
 866     bool SetItemColumnImage(long item, long column, int image);
 867
 868     /**
 869         This method can only be used with virtual list controls.
 870
 871         It is used to indicate to the control the number of items it contains.
 872         After calling it, the main program should be ready to handle calls to
 873         various item callbacks (such as wxListCtrl::OnGetItemText) for all
 874         items in the range from 0 to @a count.
 875
 876         Notice that the control is not necessarily redrawn after this call as
 877         it may be undesirable if an item which is not visible on the screen
 878         anyhow was added to or removed from a control displaying many items, if
 879         you do need to refresh the display you can just call Refresh() manually.
 880     */
 881     void SetItemCount(long count);
 882
 883     /**
 884         Associates application-defined data with this item.
 885
 886         Notice that this function cannot be used to associate pointers with the control
 887         items, use SetItemPtrData() instead.
 888     */
 889     bool SetItemData(long item, long data);
 890
 891     /**
 892          Sets the item's font.
 893     */
 894     void SetItemFont(long item, const wxFont& font);
 895
 896     /**
 897         Sets the unselected and selected images associated with the item.
 898         The images are indices into the image list associated with the list control.
 899     */
 900     bool SetItemImage(long item, int image, int selImage = -1);
 901
 902     /**
 903         Sets the unselected and selected images associated with the item.
 904         The images are indices into the image list associated with the list control.
 905
 906         @deprecated
 907         This form is deprecated: @a selImage is not used; use the other
 908         SetItemImage() overload.
 909     */
 910     bool SetItemImage(long item, int image, int selImage = -1);
 911
 912     /**
 913         Sets the position of the item, in icon or small icon view. Windows only.
 914     */
 915     bool SetItemPosition(long item, const wxPoint& pos);
 916
 917     /**
 918         Associates application-defined data with this item.
 919
 920         The @a data parameter may be either an integer or a pointer cast to the
 921         @c wxUIntPtr type which is guaranteed to be large enough to be able to
 922         contain all integer types and pointers.
 923
 924         @since 2.8.4
 925     */
 926     bool SetItemPtrData(long item, wxUIntPtr data);
 927
 928     /**
 929         Sets the item state. For a list of state flags, see SetItem().
 930         The @b stateMask indicates which state flags are valid.
 931     */
 932     bool SetItemState(long item, long state, long stateMask);
 933
 934     /**
 935         Sets the item text for this item.
 936     */
 937     void SetItemText(long item, const wxString& text);
 938
 939     /**
 940         Sets the colour for this item.
 941         This function only works in report view.
 942         The colour can be retrieved using GetItemTextColour().
 943     */
 944     void SetItemTextColour(long item, const wxColour& col);
 945
 946     /**
 947         Adds or removes a single window style.
 948     */
 949     void SetSingleStyle(long style, bool add = true);
 950
 951     /**
 952         Sets the text colour of the list control.
 953     */
 954     void SetTextColour(const wxColour& col);
 955
 956     /**
 957         Sets the whole window style, deleting all items.
 958     */
 959     void SetWindowStyleFlag(long style);
 960
 961     /**
 962         Call this function to sort the items in the list control. Sorting is done
 963         using the specified @a fnSortCallBack function. This function must have the
 964         following prototype:
 965         @code
 966         int wxCALLBACK wxListCompareFunction(wxIntPtr item1, wxIntPtr item2, wxIntPtr sortData)
 967         @endcode
 968
 969         It is called each time when the two items must be compared and should return 0
 970         if the items are equal, negative value if the first item is less than the
 971         second one and positive value if the first one is greater than the second one
 972         (the same convention as used by @c qsort(3)).
 973
 974         The parameter @e item1 is the client data associated with the first item (NOT the index).
 975         The parameter @e item2 is the client data associated with the second item (NOT the index).
 976         The parameter @e data is the value passed to SortItems() itself.
 977
 978         Notice that the control may only be sorted on client data associated with
 979         the items, so you must use SetItemData if you want to be able to sort the
 980         items in the control.
 981
 982         Please see the @ref page_samples_listctrl for an example of using this function.
 983
 984         @beginWxPerlOnly
 985         In wxPerl the comparison function must take just two parameters;
 986         however, you may use a closure to achieve an effect similar to the
 987         SortItems third parameter.
 988         @endWxPerlOnly
 989     */
 990     bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);
 991
 992 protected:
 993
 994     /**
 995         This function may be overridden in the derived class for a control with
 996         @c wxLC_VIRTUAL style. It should return the attribute for the specified
 997         @c item or @NULL to use the default appearance parameters.
 998
 999         wxListCtrl will not delete the pointer or keep a reference of it.
1000         You can return the same wxListItemAttr pointer for every OnGetItemAttr() call.
1001
1002         The base class version always returns @NULL.
1003
1004         @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
1005              OnGetItemColumnAttr()
1006     */
1007     virtual wxListItemAttr* OnGetItemAttr(long item) const;
1008
1009      /**
1010         This function may be overridden in the derived class for a control with
1011         @c wxLC_VIRTUAL style.
1012
1013         It should return the attribute for the for the specified @a item and @a
1014         column or @NULL to use the default appearance parameters.
1015
1016         The base class version returns @c OnGetItemAttr(item).
1017
1018         @note Currently this function is only called under wxMSW, the other
1019             ports only support OnGetItemAttr()
1020
1021         @see OnGetItemAttr(), OnGetItemText(),
1022              OnGetItemImage(), OnGetItemColumnImage(),
1023     */
1024     virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
1025
1026     /**
1027         Override this function in the derived class for a control with
1028         @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
1029         index for the given line and column.
1030
1031         The base class version always calls OnGetItemImage() for the first column, else
1032         it returns -1.
1033
1034         @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(),
1035              OnGetItemColumnAttr()
1036     */
1037     virtual int OnGetItemColumnImage(long item, long column) const;
1038
1039     /**
1040         This function must be overridden in the derived class for a control with
1041         @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
1042         control doesn't have an image list, it is not necessary to override it).
1043         It should return the index of the items image in the controls image list
1044         or -1 for no image.
1045
1046         In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
1047         the first column of each line.
1048
1049         The base class version always returns -1.
1050
1051         @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
1052     */
1053     virtual int OnGetItemImage(long item) const;
1054
1055     /**
1056         This function @b must be overridden in the derived class for a control with
1057         @c wxLC_VIRTUAL style. It should return the string containing the text of
1058         the given @a column for the specified @c item.
1059
1060         @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
1061     */
1062     virtual wxString OnGetItemText(long item, long column) const;
1063 };
1064
1065
1066
1067 /**
1068     @class wxListEvent
1069
1070     A list event holds information about events associated with wxListCtrl objects.
1071
1072     @beginEventTable{wxListEvent}
1073     @event{EVT_LIST_BEGIN_DRAG(id, func)}
1074         Begin dragging with the left mouse button.
1075     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
1076         Begin dragging with the right mouse button.
1077     @event{EVT_LIST_BEGIN_LABEL_EDIT(id, func)}
1078         Begin editing a label. This can be prevented by calling Veto().
1079     @event{EVT_LIST_END_LABEL_EDIT(id, func)}
1080         Finish editing a label. This can be prevented by calling Veto().
1081     @event{EVT_LIST_DELETE_ITEM(id, func)}
1082         Delete an item.
1083     @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
1084         Delete all items.
1085     @event{EVT_LIST_ITEM_SELECTED(id, func)}
1086         The item has been selected.
1087     @event{EVT_LIST_ITEM_DESELECTED(id, func)}
1088         The item has been deselected.
1089     @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
1090         The item has been activated (ENTER or double click).
1091     @event{EVT_LIST_ITEM_FOCUSED(id, func)}
1092         The currently focused item has changed.
1093     @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
1094         The middle mouse button has been clicked on an item.
1095     @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
1096         The right mouse button has been clicked on an item.
1097     @event{EVT_LIST_KEY_DOWN(id, func)}
1098         A key has been pressed. GetIndex() may be -1 if no item is selected.
1099     @event{EVT_LIST_INSERT_ITEM(id, func)}
1100         An item has been inserted.
1101     @event{EVT_LIST_COL_CLICK(id, func)}
1102         A column (m_col) has been left-clicked.
1103     @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
1104         A column (m_col) (which can be -1 if the click occurred outside any column)
1105         has been right-clicked.
1106     @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
1107         The user started resizing a column - can be vetoed.
1108     @event{EVT_LIST_COL_DRAGGING(id, func)}
1109         The divider between columns is being dragged.
1110     @event{EVT_LIST_COL_END_DRAG(id, func)}
1111         A column has been resized by the user.
1112     @event{EVT_LIST_CACHE_HINT(id, func)}
1113         Prepare cache for a virtual list control
1114     @endEventTable
1115
1116
1117     @library{wxbase}
1118     @category{events}
1119
1120     @see wxListCtrl
1121 */
1122 class wxListEvent : public wxNotifyEvent
1123 {
1124 public:
1125     /**
1126         Constructor.
1127     */
1128     wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
1129
1130     /**
1131         For @c EVT_LIST_CACHE_HINT event only: return the first item which the
1132         list control advises us to cache.
1133     */
1134     long GetCacheFrom() const;
1135
1136     /**
1137         For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
1138         which the list control advises us to cache.
1139     */
1140     long GetCacheTo() const;
1141
1142     /**
1143         The column position: it is only used with @c COL events.
1144
1145         For the column dragging events, it is the column to the left of the divider
1146         being dragged, for the column click events it may be -1 if the user clicked
1147         in the list control header outside any column.
1148     */
1149     int GetColumn() const;
1150
1151     /**
1152         The data.
1153     */
1154     long GetData() const;
1155
1156     /**
1157         The image.
1158     */
1159     int GetImage() const;
1160
1161     /**
1162         The item index.
1163     */
1164     long GetIndex() const;
1165
1166     /**
1167         An item object, used by some events. See also wxListCtrl::SetItem.
1168     */
1169     const wxListItem& GetItem() const;
1170
1171     /**
1172         Key code if the event is a keypress event.
1173     */
1174     int GetKeyCode() const;
1175
1176     /**
1177         The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
1178     */
1179     const wxString& GetLabel() const;
1180
1181     /**
1182         The mask.
1183     */
1184     long GetMask() const;
1185
1186     /**
1187         The position of the mouse pointer if the event is a drag event.
1188     */
1189     wxPoint GetPoint() const;
1190
1191     /**
1192         The text.
1193     */
1194     const wxString& GetText() const;
1195
1196     /**
1197         This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and
1198         returns @true if it the label editing has been cancelled by the user
1199         (GetLabel() returns an empty string in this case but it doesn't allow the
1200         application to distinguish between really cancelling the edit and the
1201         admittedly rare case when the user wants to rename it to an empty string).
1202     */
1203     bool IsEditCancelled() const;
1204 };
1205
1206
1207
1208 /**
1209     @class wxListItemAttr
1210
1211     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
1212
1213     @library{wxbase}
1214     @category{data}
1215
1216     @see @ref overview_listctrl, wxListCtrl, wxListItem
1217 */
1218 class wxListItemAttr
1219 {
1220 public:
1221     /**
1222         Default Constructor.
1223     */
1224     wxListItemAttr();
1225
1226     /**
1227         Construct a wxListItemAttr with the specified foreground and
1228         background colors and font.
1229     */
1230     wxListItemAttr(const wxColour& colText,
1231                    const wxColour& colBack,
1232                    const wxFont& font);
1233
1234     /**
1235         Returns the currently set background color.
1236     */
1237     const wxColour& GetBackgroundColour() const;
1238
1239     /**
1240         Returns the currently set font.
1241     */
1242     const wxFont& GetFont() const;
1243
1244     /**
1245         Returns the currently set text color.
1246     */
1247     const wxColour& GetTextColour() const;
1248
1249     /**
1250         Returns @true if the currently set background color is valid.
1251     */
1252     bool HasBackgroundColour() const;
1253
1254     /**
1255         Returns @true if the currently set font is valid.
1256     */
1257     bool HasFont() const;
1258
1259     /**
1260         Returns @true if the currently set text color is valid.
1261     */
1262     bool HasTextColour() const;
1263
1264     /**
1265         Sets a new background color.
1266     */
1267     void SetBackgroundColour(const wxColour& colour);
1268
1269     /**
1270         Sets a new font.
1271     */
1272     void SetFont(const wxFont& font);
1273
1274     /**
1275         Sets a new text color.
1276     */
1277     void SetTextColour(const wxColour& colour);
1278 };
1279
1280
1281
1282 /**
1283     @class wxListView
1284
1285     This class currently simply presents a simpler to use interface for the
1286     wxListCtrl -- it can be thought of as a @e façade for that complicated class.
1287
1288     Using it is preferable to using wxListCtrl directly whenever possible because
1289     in the future some ports might implement wxListView but not the full set of
1290     wxListCtrl features.
1291
1292     Other than different interface, this class is identical to wxListCtrl.
1293     In particular, it uses the same events, same window styles and so on.
1294
1295     @library{wxcore}
1296     @category{ctrl}
1297     @appearance{listview.png}
1298
1299     @see wxListView::SetColumnImage
1300 */
1301 class wxListView : public wxListCtrl
1302 {
1303 public:
1304     /**
1305         Resets the column image -- after calling this function, no image will be shown.
1306
1307         @param col
1308             the column to clear image for
1309
1310         @see SetColumnImage()
1311     */
1312     void ClearColumnImage(int col);
1313
1314     /**
1315         Sets focus to the item with the given @a index.
1316     */
1317     void Focus(long index);
1318
1319     /**
1320         Returns the first selected item in a (presumably) multiple selection control.
1321         Together with GetNextSelected() it can be used to iterate over all selected
1322         items in the control.
1323
1324         @return The first selected item, if any, -1 otherwise.
1325     */
1326     long GetFirstSelected() const;
1327
1328     /**
1329         Returns the currently focused item or -1 if none.
1330
1331         @see IsSelected(), Focus()
1332     */
1333     long GetFocusedItem() const;
1334
1335     /**
1336         Used together with GetFirstSelected() to iterate over all selected items
1337         in the control.
1338
1339         @return Returns the next selected item or -1 if there are no more of them.
1340     */
1341     long GetNextSelected(long item) const;
1342
1343     /**
1344         Returns @true if the item with the given @a index is selected,
1345         @false otherwise.
1346
1347         @see GetFirstSelected(), GetNextSelected()
1348     */
1349     bool IsSelected(long index) const;
1350
1351     /**
1352         Selects or unselects the given item.
1353
1354         @param n
1355             the item to select or unselect
1356         @param on
1357             if @true (default), selects the item, otherwise unselects it
1358
1359         @see wxListCtrl::SetItemState
1360     */
1361     void Select(long n, bool on = true);
1362
1363     /**
1364         Sets the column image for the specified column.
1365         To use the column images, the control must have a valid image list with
1366         at least one image.
1367
1368         @param col
1369             the column to set image for
1370         @param image
1371             the index of the column image in the controls image list
1372     */
1373     void SetColumnImage(int col, int image);
1374 };
1375
1376
1377 /**
1378     Column format (MSW only except wxLIST_FORMAT_LEFT).
1379 */
1380 enum wxListColumnFormat
1381 {
1382     wxLIST_FORMAT_LEFT,
1383     wxLIST_FORMAT_RIGHT,
1384     wxLIST_FORMAT_CENTRE,
1385     wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE
1386 };
1387
1388 /**
1389     @class wxListItem
1390
1391     This class stores information about a wxListCtrl item or column.
1392
1393     wxListItem is a class which contains informations about:
1394     - Zero based item position; see SetId() and GetId().
1395     - Zero based column index; see SetColumn() and GetColumn().
1396     - The label (or header for columns); see SetText() and GetText().
1397     - The zero based index into an image list; see GetImage() and SetImage().
1398     - Application defined data; see SetData() and GetData().
1399     - For columns only: the width of the column; see SetWidth() and GetWidth().
1400     - For columns only: the format of the column; one of @c wxLIST_FORMAT_LEFT,
1401       @c wxLIST_FORMAT_RIGHT, @c wxLIST_FORMAT_CENTRE. See SetAlign() and GetAlign().
1402     - The state of the item; see SetState() and GetState().
1403       This is a bitlist of the following flags:
1404         - @c wxLIST_STATE_FOCUSED: The item has the focus.
1405         - @c wxLIST_STATE_SELECTED: The item is selected.
1406         - @c wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1407         - @c wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1408         - @c wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1409     - A mask indicating which state flags are valid; this is a bitlist of the
1410       flags reported above for the item state. See SetStateMask() and GetStateMask().
1411     - A mask indicating which fields of this class are valid; see SetMask() and GetMask().
1412       This is a bitlist of the following flags:
1413         - @c wxLIST_MASK_STATE: The state field is valid.
1414         - @c wxLIST_MASK_TEXT: The label field is valid.
1415         - @c wxLIST_MASK_IMAGE: The image field is valid.
1416         - @c wxLIST_MASK_DATA: The application-defined data field is valid.
1417         - @c wxLIST_MASK_WIDTH: The column width field is valid.
1418         - @c wxLIST_MASK_FORMAT: The column format field is valid.
1419
1420     The wxListItem object can also contain item-specific colour and font
1421     information: for this you need to call one of SetTextColour(), SetBackgroundColour()
1422     or SetFont() functions on it passing it the colour/font to use.
1423     If the colour/font is not specified, the default list control colour/font is used.
1424
1425     @library{wxbase}
1426     @category{data}
1427
1428     @see wxListCtrl
1429 */
1430 class wxListItem : public wxObject
1431 {
1432 public:
1433     /**
1434         Constructor.
1435     */
1436     wxListItem();
1437
1438     /**
1439         Resets the item state to the default.
1440     */
1441     void Clear();
1442
1443     /**
1444         Returns the alignment for this item.
1445         Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or @c wxLIST_FORMAT_CENTRE.
1446     */
1447     wxListColumnFormat GetAlign() const;
1448
1449     /**
1450         Returns the background colour for this item.
1451     */
1452     wxColour GetBackgroundColour() const;
1453
1454     /**
1455         Returns the zero-based column; meaningful only in report mode.
1456     */
1457     int GetColumn() const;
1458
1459     /**
1460         Returns client data associated with the control.
1461         Please note that client data is associated with the item and not with subitems.
1462     */
1463     wxUIntPtr GetData() const;
1464
1465     /**
1466         Returns the font used to display the item.
1467     */
1468     wxFont GetFont() const;
1469
1470     /**
1471         Returns the zero-based item position.
1472     */
1473     long GetId() const;
1474
1475     /**
1476         Returns the zero-based index of the image associated with the item into
1477         the image list.
1478     */
1479     int GetImage() const;
1480
1481     /**
1482         Returns a bit mask indicating which fields of the structure are valid.
1483
1484         Can be any combination of the following values:
1485         - wxLIST_MASK_STATE: @b GetState is valid.
1486         - wxLIST_MASK_TEXT: @b GetText is valid.
1487         - wxLIST_MASK_IMAGE: @b GetImage is valid.
1488         - wxLIST_MASK_DATA: @b GetData is valid.
1489         - wxLIST_MASK_WIDTH: @b GetWidth is valid.
1490         - wxLIST_MASK_FORMAT: @b GetFormat is valid.
1491     */
1492     long GetMask() const;
1493
1494     /**
1495         Returns a bit field representing the state of the item.
1496
1497         Can be any combination of:
1498         - wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1499         - wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1500         - wxLIST_STATE_FOCUSED: The item has the focus.
1501         - wxLIST_STATE_SELECTED: The item is selected.
1502         - wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1503     */
1504     long GetState() const;
1505
1506     /**
1507         Returns the label/header text.
1508     */
1509     const wxString& GetText() const;
1510
1511     /**
1512         Returns the text colour.
1513     */
1514     wxColour GetTextColour() const;
1515
1516     /**
1517         Meaningful only for column headers in report mode. Returns the column width.
1518     */
1519     int GetWidth() const;
1520
1521     /**
1522         Sets the alignment for the item. See also GetAlign()
1523     */
1524     void SetAlign(wxListColumnFormat align);
1525
1526     /**
1527         Sets the background colour for the item.
1528     */
1529     void SetBackgroundColour(const wxColour& colBack);
1530
1531     /**
1532         Sets the zero-based column. Meaningful only in report mode.
1533     */
1534     void SetColumn(int col);
1535
1536     //@{
1537     /**
1538         Sets client data for the item.
1539         Please note that client data is associated with the item and not with subitems.
1540     */
1541     void SetData(long data);
1542     void SetData(void* data);
1543     //@}
1544
1545     /**
1546         Sets the font for the item.
1547     */
1548     void SetFont(const wxFont& font);
1549
1550     /**
1551         Sets the zero-based item position.
1552     */
1553     void SetId(long id);
1554
1555     /**
1556         Sets the zero-based index of the image associated with the item
1557         into the image list.
1558     */
1559     void SetImage(int image);
1560
1561     /**
1562         Sets the mask of valid fields. See GetMask().
1563     */
1564     void SetMask(long mask);
1565
1566     /**
1567         Sets the item state flags (note that the valid state flags are influenced
1568         by the value of the state mask, see wxListItem::SetStateMask).
1569
1570         See GetState() for valid flag values.
1571     */
1572     void SetState(long state);
1573
1574     /**
1575         Sets the bitmask that is used to determine which of the state flags
1576         are to be set. See also SetState().
1577     */
1578     void SetStateMask(long stateMask);
1579
1580     /**
1581         Sets the text label for the item.
1582     */
1583     void SetText(const wxString& text);
1584
1585     /**
1586         Sets the text colour for the item.
1587     */
1588     void SetTextColour(const wxColour& colText);
1589
1590     /**
1591         Meaningful only for column headers in report mode. Sets the column width.
1592     */
1593     void SetWidth(int width);
1594 };
1595