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