interface/listctrl.h

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