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         @since 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.
 836
 837         It is used to indicate to the control the number of items it contains.
 838         After calling it, the main program should be ready to handle calls to
 839         various item callbacks (such as wxListCtrl::OnGetItemText) for all
 840         items in the range from 0 to @a count.
 841
 842         Notice that the control is not necessarily redrawn after this call as
 843         it may be undesirable if an item which is not visible on the screen
 844         anyhow was added to or removed from a control displaying many items, if
 845         you do need to refresh the display you can just call Refresh() manually.
 846     */
 847     void SetItemCount(long count);
 848
 849     /**
 850     Associates application-defined data with this item.
 851     Notice that this function cannot be used to associate pointers with the control
 852     items, use SetItemPtrData() instead.
 853     */
 854     bool SetItemData(long item, long data);
 855
 856     /**
 857     Sets the item's font.
 858     */
 859     void SetItemFont(long item, const wxFont& font);
 860
 861     //@{
 862     /**
 863         Sets the unselected and selected images associated with the item. The images
 864         are indices into the
 865         image list associated with the list control. This form is deprecated: @a
 866         selImage is not
 867         used.
 868     */
 869     bool SetItemImage(long item, int image);
 870     bool SetItemImage(long item, int image, int selImage);
 871     //@}
 872
 873     /**
 874         Sets the position of the item, in icon or small icon view. Windows only.
 875     */
 876     bool SetItemPosition(long item, const wxPoint& pos);
 877
 878     /**
 879         Associates application-defined data with this item. The @a data parameter may
 880         be either an integer or a pointer cast to the @c wxUIntPtr type which is
 881         guaranteed to be large enough to be able to contain all integer types and
 882         pointers.
 883
 884         @since 2.8.4
 885     */
 886     bool SetItemPtrData(long item, wxUIntPtr data);
 887
 888     /**
 889         Sets the item state. For a list of state flags, see SetItem().
 890         The @b stateMask indicates which state flags are valid.
 891     */
 892     bool SetItemState(long item, long state, long stateMask);
 893
 894     /**
 895         Sets the item text for this item.
 896     */
 897     void SetItemText(long item, const wxString& text);
 898
 899     /**
 900         Sets the colour for this item. This function only works in report view.
 901         The colour can be retrieved using
 902         GetItemTextColour().
 903     */
 904     void SetItemTextColour(long item, const wxColour& col);
 905
 906     /**
 907         Adds or removes a single window style.
 908     */
 909     void SetSingleStyle(long style, bool add = true);
 910
 911     /**
 912         Sets the text colour of the list control.
 913     */
 914     void SetTextColour(const wxColour& col);
 915
 916     /**
 917         Sets the whole window style, deleting all items.
 918     */
 919     void SetWindowStyleFlag(long style);
 920
 921     /**
 922         Call this function to sort the items in the list control. Sorting is done
 923         using the specified @a fnSortCallBack function. This function must have the
 924         following prototype:
 925
 926         It is called each time when the two items must be compared and should return 0
 927         if the items are equal, negative value if the first item is less than the
 928         second one and positive value if the first one is greater than the second one
 929         (the same convention as used by @c qsort(3)).
 930
 931         @param item1
 932             client data associated with the first item (NOT the index).
 933         @param item2
 934             client data associated with the second item (NOT the index).
 935         @param data
 936             the value passed to SortItems() itself.
 937     */
 938     bool SortItems(wxListCtrlCompare fnSortCallBack, long data);
 939 };
 940
 941
 942
 943 /**
 944     @class wxListEvent
 945     @wxheader{listctrl.h}
 946
 947     A list event holds information about events associated with wxListCtrl objects.
 948
 949     @library{wxbase}
 950     @category{events}
 951
 952     @see wxListCtrl
 953 */
 954 class wxListEvent : public wxNotifyEvent
 955 {
 956 public:
 957     /**
 958         Constructor.
 959     */
 960     wxListEvent(wxEventType commandType = 0, int id = 0);
 961
 962     /**
 963         For @c EVT_LIST_CACHE_HINT event only: return the first item which the
 964         list control advises us to cache.
 965     */
 966     long GetCacheFrom() const;
 967
 968     /**
 969         For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
 970         which the list control advises us to cache.
 971     */
 972     long GetCacheTo() const;
 973
 974     /**
 975         The column position: it is only used with @c COL events. For the column
 976         dragging events, it is the column to the left of the divider being dragged, for
 977         the column click events it may be -1 if the user clicked in the list control
 978         header outside any column.
 979     */
 980     int GetColumn() const;
 981
 982     /**
 983         The data.
 984     */
 985     long GetData() const;
 986
 987     /**
 988         The image.
 989     */
 990     int GetImage() const;
 991
 992     /**
 993         The item index.
 994     */
 995     long GetIndex() const;
 996
 997     /**
 998         An item object, used by some events. See also wxListCtrl::SetItem.
 999     */
1000     const wxListItem GetItem() const;
1001
1002     /**
1003         Key code if the event is a keypress event.
1004     */
1005     int GetKeyCode() const;
1006
1007     /**
1008         The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
1009     */
1010     const wxString GetLabel() const;
1011
1012     /**
1013         The mask.
1014     */
1015     long GetMask() const;
1016
1017     /**
1018         The position of the mouse pointer if the event is a drag event.
1019     */
1020     wxPoint GetPoint() const;
1021
1022     /**
1023         The text.
1024     */
1025     const wxString GetText() const;
1026
1027     /**
1028         This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message
1029         and returns @true if it the label editing has been cancelled by the user
1030         (GetLabel() returns an empty string in this case
1031         but it doesn't allow the application to distinguish between really cancelling
1032         the edit and
1033         the admittedly rare case when the user wants to rename it to an empty string).
1034     */
1035     bool IsEditCancelled() const;
1036 };
1037
1038
1039
1040 /**
1041     @class wxListItemAttr
1042     @wxheader{listctrl.h}
1043
1044     Represents the attributes (color, font, ...) of a
1045     wxListCtrl wxListItem.
1046
1047     @library{wxbase}
1048     @category{FIXME}
1049
1050     @see @ref overview_wxlistctrloverview "wxListCtrl overview", wxListCtrl,
1051     wxListItem
1052 */
1053 class wxListItemAttr
1054 {
1055 public:
1056     //@{
1057     /**
1058         Construct a wxListItemAttr with the specified foreground and
1059         background colors and font.
1060     */
1061     wxListItemAttr();
1062     wxListItemAttr(const wxColour colText,
1063                    const wxColour colBack,
1064                    const wxFont font);
1065     //@}
1066
1067     /**
1068         Returns the currently set background color.
1069     */
1070     const wxColour GetBackgroundColour() const;
1071
1072     /**
1073         Returns the currently set font.
1074     */
1075     const wxFont GetFont() const;
1076
1077     /**
1078         Returns the currently set text color.
1079     */
1080     const wxColour GetTextColour() const;
1081
1082     /**
1083         Returns @true if the currently set background color is valid.
1084     */
1085     bool HasBackgroundColour() const;
1086
1087     /**
1088         Returns @true if the currently set font is valid.
1089     */
1090     bool HasFont() const;
1091
1092     /**
1093         Returns @true if the currently set text color is valid.
1094     */
1095     bool HasTextColour() const;
1096
1097     /**
1098         Sets a new background color.
1099     */
1100     void SetBackgroundColour(const wxColour& colour);
1101
1102     /**
1103         Sets a new font.
1104     */
1105     void SetFont(const wxFont& font);
1106
1107     /**
1108         Sets a new text color.
1109     */
1110     void SetTextColour(const wxColour& colour);
1111 };
1112
1113
1114
1115 /**
1116     @class wxListView
1117     @wxheader{listctrl.h}
1118
1119     This class currently simply presents a simpler to use interface for the
1120     wxListCtrl -- it can be thought of as a @e faade
1121     for that complicated class. Using it is preferable to using
1122     wxListCtrl directly whenever possible because in the
1123     future some ports might implement wxListView but not the full set of wxListCtrl
1124     features.
1125
1126     Other than different interface, this class is identical to wxListCtrl. In
1127     particular, it uses the same events, same window styles and so on.
1128
1129     @library{wxcore}
1130     @category{ctrl}
1131     <!-- @appearance{listview.png} -->
1132
1133     @see wxListView::SetColumnImage
1134 */
1135 class wxListView : public wxListCtrl
1136 {
1137 public:
1138     /**
1139         Resets the column image -- after calling this function, no image will be shown.
1140
1141         @param col
1142             the column to clear image for
1143
1144         @see SetColumnImage()
1145     */
1146     void ClearColumnImage(int col);
1147
1148     /**
1149         Sets focus to the item with the given @e index.
1150     */
1151     void Focus(long index);
1152
1153     /**
1154         Returns the first selected item in a (presumably) multiple selection control.
1155         Together with GetNextSelected() it can be
1156         used to iterate over all selected items in the control.
1157
1158         @return The first selected item, if any, -1 otherwise.
1159     */
1160     long GetFirstSelected() const;
1161
1162     /**
1163         Returns the currently focused item or -1 if none.
1164
1165         @see IsSelected(), Focus()
1166     */
1167     long GetFocusedItem() const;
1168
1169     /**
1170         Used together with GetFirstSelected() to
1171         iterate over all selected items in the control.
1172
1173         @return Returns the next selected item or -1 if there are no more of
1174                  them.
1175     */
1176     long GetNextSelected(long item) const;
1177
1178     /**
1179         Returns @true if the item with the given @a index is selected,
1180         @false otherwise.
1181
1182         @see GetFirstSelected(), GetNextSelected()
1183     */
1184     bool IsSelected(long index) const;
1185
1186     /**
1187         Selects or unselects the given item.
1188
1189         @param n
1190             the item to select or unselect
1191         @param on
1192             if @true (default), selects the item, otherwise unselects it
1193
1194         @see wxListCtrl::SetItemState
1195     */
1196     void Select(bool on = true);
1197
1198     /**
1199         Sets the column image for the specified column. To use the column images, the
1200         control must have a valid image list with at least one image.
1201
1202         @param col
1203             the column to set image for
1204         @param image
1205             the index of the column image in the controls image list
1206     */
1207     void SetColumnImage(int col, int image);
1208 };
1209
1210
1211
1212 /**
1213     @class wxListItem
1214     @wxheader{listctrl.h}
1215
1216     This class stores information about a wxListCtrl item or column.
1217
1218     @library{wxbase}
1219     @category{FIXME}
1220 */
1221 class wxListItem : public wxObject
1222 {
1223 public:
1224     /**
1225         Constructor.
1226     */
1227     wxListItem();
1228
1229     /**
1230         Resets the item state to the default.
1231     */
1232     void Clear();
1233
1234     /**
1235         Returns the alignment for this item. Can be one of
1236         wxLIST_FORMAT_LEFT, wxLIST_FORMAT_RIGHT or wxLIST_FORMAT_CENTRE.
1237     */
1238     wxListColumnFormat GetAlign() const;
1239
1240     /**
1241         Returns the background colour for this item.
1242     */
1243     wxColour GetBackgroundColour() const;
1244
1245     /**
1246         Returns the zero-based column; meaningful only in report mode.
1247     */
1248     int GetColumn() const;
1249
1250     /**
1251         Returns client data associated with the control. Please note that
1252         client data is associated with the item and not with subitems.
1253     */
1254     long GetData() const;
1255
1256     /**
1257         Returns the font used to display the item.
1258     */
1259     wxFont GetFont() const;
1260
1261     /**
1262         Returns the zero-based item position.
1263     */
1264     long GetId() const;
1265
1266     /**
1267         Returns the zero-based index of the image
1268         associated with the item into the image list.
1269     */
1270     int GetImage() const;
1271
1272     /**
1273         Returns a bit mask indicating which fields of the structure are valid;
1274         can be any combination of the following values:
1275
1276         wxLIST_MASK_STATE
1277
1278         @b GetState is valid.
1279
1280         wxLIST_MASK_TEXT
1281
1282         @b GetText is valid.
1283
1284         wxLIST_MASK_IMAGE
1285
1286         @b GetImage is valid.
1287
1288         wxLIST_MASK_DATA
1289
1290         @b GetData is valid.
1291
1292         wxLIST_MASK_WIDTH
1293
1294         @b GetWidth is valid.
1295
1296         wxLIST_MASK_FORMAT
1297
1298         @b GetFormat is valid.
1299     */
1300     long GetMask() const;
1301
1302     /**
1303         Returns a bit field representing the state of the item. Can be any
1304         combination of:
1305
1306         wxLIST_STATE_DONTCARE
1307
1308         Don't care what the state is. Win32 only.
1309
1310         wxLIST_STATE_DROPHILITED
1311
1312         The item is highlighted to receive a drop event. Win32 only.
1313
1314         wxLIST_STATE_FOCUSED
1315
1316         The item has the focus.
1317
1318         wxLIST_STATE_SELECTED
1319
1320         The item is selected.
1321
1322         wxLIST_STATE_CUT
1323
1324         The item is in the cut state. Win32 only.
1325     */
1326     long GetState() const;
1327
1328     /**
1329         Returns the label/header text.
1330     */
1331     const wxString GetText() const;
1332
1333     /**
1334         Returns the text colour.
1335     */
1336     wxColour GetTextColour() const;
1337
1338     /**
1339         Meaningful only for column headers in report mode. Returns the column width.
1340     */
1341     int GetWidth() const;
1342
1343     /**
1344         Sets the alignment for the item. See also
1345         GetAlign()
1346     */
1347     void SetAlign(wxListColumnFormat align);
1348
1349     /**
1350         Sets the background colour for the item.
1351     */
1352     void SetBackgroundColour(const wxColour& colBack);
1353
1354     /**
1355         Sets the zero-based column. Meaningful only in report mode.
1356     */
1357     void SetColumn(int col);
1358
1359     //@{
1360     /**
1361         Sets client data for the item. Please note that
1362         client data is associated with the item and not with subitems.
1363     */
1364     void SetData(long data);
1365     void SetData(void* data);
1366     //@}
1367
1368     /**
1369         Sets the font for the item.
1370     */
1371     void SetFont(const wxFont& font);
1372
1373     /**
1374         Sets the zero-based item position.
1375     */
1376     void SetId(long id);
1377
1378     /**
1379         Sets the zero-based index of the image associated with the item
1380         into the image list.
1381     */
1382     void SetImage(int image);
1383
1384     /**
1385         Sets the mask of valid fields. See GetMask().
1386     */
1387     void SetMask(long mask);
1388
1389     /**
1390         Sets the item state flags (note that the valid state flags are influenced
1391         by the value of the state mask, see
1392         wxListItem::SetStateMask).
1393         See GetState() for valid flag
1394         values.
1395     */
1396     void SetState(long state);
1397
1398     /**
1399         Sets the bitmask that is used to determine which of the state flags
1400         are to be set. See also SetState().
1401     */
1402     void SetStateMask(long stateMask);
1403
1404     /**
1405         Sets the text label for the item.
1406     */
1407     void SetText(const wxString& text);
1408
1409     /**
1410         Sets the text colour for the item.
1411     */
1412     void SetTextColour(const wxColour& colText);
1413
1414     /**
1415         Meaningful only for column headers in report mode. Sets the column width.
1416     */
1417     void SetWidth(int width);
1418 };
1419