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