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