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