interface/listctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        listctrl.h
   3 // Purpose:     documentation for wxListCtrl class
   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     @seealso
  90     @ref overview_wxlistctrloverview "wxListCtrl overview", wxListView, wxListBox,
  91     wxTreeCtrl, wxImageList, wxListEvent, wxListItem
  92 */
  93 class wxListCtrl : public wxControl
  94 {
  95 public:
  96     //@{
  97     /**
  98         Constructor, creating and showing a list control.
  99
 100         @param parent
 101             Parent window. Must not be @NULL.
 102         @param id
 103             Window identifier. The value wxID_ANY indicates a default value.
 104         @param pos
 105             Window position.
 106         @param size
 107             Window size. If wxDefaultSize is specified then the window is
 108         sized
 109             appropriately.
 110         @param style
 111             Window style. See wxListCtrl.
 112         @param validator
 113             Window validator.
 114         @param name
 115             Window name.
 116
 117         @see Create(), wxValidator
 118     */
 119     wxListCtrl();
 120     wxListCtrl(wxWindow* parent, wxWindowID id,
 121                const wxPoint& pos = wxDefaultPosition,
 122                const wxSize& size = wxDefaultSize,
 123                long style = wxLC_ICON,
 124                const wxValidator& validator = wxDefaultValidator,
 125                const wxString& name = wxListCtrlNameStr);
 126     //@}
 127
 128     /**
 129         Destructor, destroying the list control.
 130     */
 131     ~wxListCtrl();
 132
 133     /**
 134         Arranges the items in icon or small icon view. This only has effect on Win32.
 135         @a flag is one of:
 136
 137         wxLIST_ALIGN_DEFAULT
 138
 139         Default alignment.
 140
 141         wxLIST_ALIGN_LEFT
 142
 143         Align to the left side of the control.
 144
 145         wxLIST_ALIGN_TOP
 146
 147         Align to the top side of the control.
 148
 149         wxLIST_ALIGN_SNAP_TO_GRID
 150
 151         Snap to grid.
 152     */
 153     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 154
 155     /**
 156         Sets the image list associated with the control and
 157         takes ownership of it (i.e. the control will, unlike when using
 158         SetImageList, delete the list when destroyed). @a which is one of
 159         wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is
 160         unimplemented).
 161
 162         @see SetImageList()
 163     */
 164     void AssignImageList(wxImageList* imageList, int which);
 165
 166     /**
 167         Deletes all items and all columns.
 168     */
 169     void ClearAll();
 170
 171     /**
 172         Creates the list control. See wxListCtrl() for further details.
 173     */
 174     bool Create(wxWindow* parent, wxWindowID id,
 175                 const wxPoint& pos = wxDefaultPosition,
 176                 const wxSize& size = wxDefaultSize,
 177                 long style = wxLC_ICON,
 178                 const wxValidator& validator = wxDefaultValidator,
 179                 const wxString& name = wxListCtrlNameStr);
 180
 181     /**
 182         Deletes all items in the list control.
 183         @b NB: This function does @e not send the
 184         @c wxEVT_COMMAND_LIST_DELETE_ITEM event because deleting many items
 185         from the control would be too slow then (unlike wxListCtrl::DeleteItem).
 186     */
 187     bool DeleteAllItems();
 188
 189     /**
 190         Deletes a column.
 191     */
 192     bool DeleteColumn(int col);
 193
 194     /**
 195         Deletes the specified item. This function sends the
 196         @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the item being deleted.
 197         See also: DeleteAllItems()
 198     */
 199     bool DeleteItem(long item);
 200
 201     /**
 202         Starts editing the label of the given item. This function generates a
 203         EVT_LIST_BEGIN_LABEL_EDIT event which can be vetoed so that no
 204         text control will appear for in-place editing.
 205         If the user changed the label (i.e. s/he does not press ESC or leave
 206         the text control without changes, a EVT_LIST_END_LABEL_EDIT event
 207         will be sent which can be vetoed as well.
 208     */
 209     void EditLabel(long item);
 210
 211     /**
 212         Ensures this item is visible.
 213     */
 214     bool EnsureVisible(long item);
 215
 216     //@{
 217     /**
 218         Find an item nearest this position in the specified direction, starting from
 219         @a start or the beginning if @a start is -1.
 220
 221
 222         @b FindItem( start, str, partial = @false )
 223
 224
 225         @b FindItemData( start, data )
 226
 227
 228         @b FindItemAtPos( start, point, direction )
 229     */
 230     long FindItem(long start, const wxString& str,
 231                   bool partial = false);
 232     long FindItem(long start, long data);
 233     long FindItem(long start, const wxPoint& pt, int direction);
 234     //@}
 235
 236     /**
 237         Gets information about this column. See SetItem() for more
 238         information.
 239     */
 240     bool GetColumn(int col, wxListItem& item) const;
 241
 242     /**
 243         Returns the number of columns.
 244     */
 245     int GetColumnCount() const;
 246
 247     /**
 248         Gets the column number by visual order index (report view only).
 249     */
 250     int GetColumnIndexFromOrder(int order) const;
 251
 252     /**
 253         Gets the column visual order index (valid in report view only).
 254     */
 255     int GetColumnOrder(int col) const;
 256
 257     /**
 258         Gets the column width (report view only).
 259     */
 260     int GetColumnWidth(int col) const;
 261
 262     /**
 263         Returns the array containing the orders of all columns. On error, an empty
 264         array is returned.
 265     */
 266     wxArrayInt GetColumnsOrder() const;
 267
 268     /**
 269         Gets the number of items that can fit vertically in the
 270         visible area of the list control (list or report view)
 271         or the total number of items in the list control (icon
 272         or small icon view).
 273     */
 274     int GetCountPerPage() const;
 275
 276     /**
 277         Returns the edit control being currently used to edit a label. Returns @NULL
 278         if no label is being edited.
 279         @b NB: It is currently only implemented for wxMSW and the generic version,
 280         not for the native Mac OS X version.
 281     */
 282     wxTextCtrl* GetEditControl() const;
 283
 284     /**
 285         Returns the specified image list. @a which may be one of:
 286
 287         @b wxIMAGE_LIST_NORMAL
 288
 289         The normal (large icon) image list.
 290
 291         @b wxIMAGE_LIST_SMALL
 292
 293         The small icon image list.
 294
 295         @b wxIMAGE_LIST_STATE
 296
 297         The user-defined state image list (unimplemented).
 298     */
 299     wxImageList* GetImageList(int which) const;
 300
 301     /**
 302         Gets information about the item. See SetItem() for more
 303         information.
 304         You must call @e info.SetId() to the ID of item you're interested in
 305         before calling this method.
 306     */
 307     bool GetItem(wxListItem& info) const;
 308
 309     /**
 310         Returns the colour for this item. If the item has no specific colour, returns
 311         an invalid colour (and not the default background control of the control
 312         itself).
 313
 314         @see GetItemTextColour()
 315     */
 316     wxColour GetItemBackgroundColour(long item) const;
 317
 318     /**
 319         Returns the number of items in the list control.
 320     */
 321     int GetItemCount() const;
 322
 323     /**
 324         Gets the application-defined data associated with this item.
 325     */
 326     long GetItemData(long item) const;
 327
 328     /**
 329         Returns the item's font.
 330     */
 331     wxFont GetItemFont(long item) const;
 332
 333     /**
 334         Returns the position of the item, in icon or small icon view.
 335     */
 336     bool GetItemPosition(long item, wxPoint& pos) const;
 337
 338     /**
 339         Returns the rectangle representing the item's size and position, in physical
 340         coordinates.
 341         @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
 342     */
 343     bool GetItemRect(long item, wxRect& rect,
 344                      int code = wxLIST_RECT_BOUNDS) const;
 345
 346     /**
 347         Retrieves the spacing between icons in pixels: horizontal spacing is returned
 348         as @c x component of the wxSize object and the vertical
 349         spacing as its @c y component.
 350     */
 351     wxSize GetItemSpacing() const;
 352
 353     /**
 354         Gets the item state. For a list of state flags, see SetItem().
 355         The @b stateMask indicates which state flags are of interest.
 356     */
 357     int GetItemState(long item, long stateMask) const;
 358
 359     /**
 360         Gets the item text for this item.
 361     */
 362     wxString GetItemText(long item) const;
 363
 364     /**
 365         Returns the colour for this item. If the item has no specific colour, returns
 366         an invalid colour (and not the default foreground control of the control itself
 367         as this wouldn't allow distinguishing between items having the same colour as
 368         the current control foreground and items with default colour which, hence, have
 369         always the same colour as the control).
 370     */
 371     wxColour GetItemTextColour(long item) const;
 372
 373     /**
 374         Searches for an item with the given geometry or state, starting from
 375         @a item but excluding the @a item itself. If @a item is -1,
 376         the first item that matches the specified flags will be returned.
 377         Returns the first item with given state following @a item or -1 if
 378         no such item found.
 379         This function may be used to find all selected items in the control like this:
 380
 381         @a geometry can be one of:
 382
 383         wxLIST_NEXT_ABOVE
 384
 385         Searches for an item above the specified item.
 386
 387         wxLIST_NEXT_ALL
 388
 389         Searches for subsequent item by index.
 390
 391         wxLIST_NEXT_BELOW
 392
 393         Searches for an item below the specified item.
 394
 395         wxLIST_NEXT_LEFT
 396
 397         Searches for an item to the left of the specified item.
 398
 399         wxLIST_NEXT_RIGHT
 400
 401         Searches for an item to the right of the specified item.
 402
 403         @b NB: this parameter is only supported by wxMSW currently and ignored on
 404         other platforms.
 405         @a state can be a bitlist of the following:
 406
 407         wxLIST_STATE_DONTCARE
 408
 409         Don't care what the state is.
 410
 411         wxLIST_STATE_DROPHILITED
 412
 413         The item indicates it is a drop target.
 414
 415         wxLIST_STATE_FOCUSED
 416
 417         The item has the focus.
 418
 419         wxLIST_STATE_SELECTED
 420
 421         The item is selected.
 422
 423         wxLIST_STATE_CUT
 424
 425         The item is selected as part of a cut and paste operation.
 426     */
 427     long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL,
 428                      int state = wxLIST_STATE_DONTCARE) const;
 429
 430     /**
 431         Returns the number of selected items in the list control.
 432     */
 433     int GetSelectedItemCount() const;
 434
 435     /**
 436         Returns the rectangle representing the size and position, in physical
 437         coordinates, of the given subitem, i.e. the part of the row @a item in the
 438         column @e subItem.
 439         This method is only meaningfull when the wxListCtrl is in the report mode. If
 440         @a subItem parameter is equal to the special value
 441         @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
 442         for GetItemRect().
 443         @a code can be one of @c wxLIST_RECT_BOUNDS,
 444         @c wxLIST_RECT_ICON or @c wxLIST_RECT_LABEL.
 445         This function is new since wxWidgets version 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         @b NB: 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         This function is new since wxWidgets version 2.8.4
 878     */
 879     bool SetItemPtrData(long item, wxUIntPtr data);
 880
 881     /**
 882         Sets the item state. For a list of state flags, see SetItem().
 883         The @b stateMask indicates which state flags are valid.
 884     */
 885     bool SetItemState(long item, long state, long stateMask);
 886
 887     /**
 888         Sets the item text for this item.
 889     */
 890     void SetItemText(long item, const wxString& text);
 891
 892     /**
 893         Sets the colour for this item. This function only works in report view.
 894         The colour can be retrieved using
 895         GetItemTextColour().
 896     */
 897     void SetItemTextColour(long item, const wxColour& col);
 898
 899     /**
 900         Adds or removes a single window style.
 901     */
 902     void SetSingleStyle(long style, bool add = true);
 903
 904     /**
 905         Sets the text colour of the list control.
 906     */
 907     void SetTextColour(const wxColour& col);
 908
 909     /**
 910         Sets the whole window style, deleting all items.
 911     */
 912     void SetWindowStyleFlag(long style);
 913
 914     /**
 915         Call this function to sort the items in the list control. Sorting is done
 916         using the specified @a fnSortCallBack function. This function must have the
 917         following prototype:
 918
 919         It is called each time when the two items must be compared and should return 0
 920         if the items are equal, negative value if the first item is less than the
 921         second one and positive value if the first one is greater than the second one
 922         (the same convention as used by @c qsort(3)).
 923
 924         @param item1
 925             client data associated with the first item (NOT the index).
 926         @param item2
 927             client data associated with the second item (NOT the index).
 928         @param data
 929             the value passed to SortItems() itself.
 930     */
 931     bool SortItems(wxListCtrlCompare fnSortCallBack, long data);
 932 };
 933
 934
 935 /**
 936     @class wxListEvent
 937     @wxheader{listctrl.h}
 938
 939     A list event holds information about events associated with wxListCtrl objects.
 940
 941     @library{wxbase}
 942     @category{events}
 943
 944     @seealso
 945     wxListCtrl
 946 */
 947 class wxListEvent : public wxNotifyEvent
 948 {
 949 public:
 950     /**
 951         Constructor.
 952     */
 953     wxListEvent(WXTYPE commandType = 0, int id = 0);
 954
 955     /**
 956         For @c EVT_LIST_CACHE_HINT event only: return the first item which the
 957         list control advises us to cache.
 958     */
 959     long GetCacheFrom() const;
 960
 961     /**
 962         For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
 963         which the list control advises us to cache.
 964     */
 965     long GetCacheTo() const;
 966
 967     /**
 968         The column position: it is only used with @c COL events. For the column
 969         dragging events, it is the column to the left of the divider being dragged, for
 970         the column click events it may be -1 if the user clicked in the list control
 971         header outside any column.
 972     */
 973     int GetColumn() const;
 974
 975     /**
 976         The data.
 977     */
 978     long GetData() const;
 979
 980     /**
 981         The image.
 982     */
 983     int GetImage() const;
 984
 985     /**
 986         The item index.
 987     */
 988     long GetIndex() const;
 989
 990     /**
 991         An item object, used by some events. See also wxListCtrl::SetItem.
 992     */
 993     const wxListItem GetItem() const;
 994
 995     /**
 996         Key code if the event is a keypress event.
 997     */
 998     int GetKeyCode() const;
 999
1000     /**
1001         The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
1002     */
1003     const wxString GetLabel() const;
1004
1005     /**
1006         The mask.
1007     */
1008     long GetMask() const;
1009
1010     /**
1011         The position of the mouse pointer if the event is a drag event.
1012     */
1013     wxPoint GetPoint() const;
1014
1015     /**
1016         The text.
1017     */
1018     const wxString GetText() const;
1019
1020     /**
1021         This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message
1022         and returns @true if it the label editing has been cancelled by the user
1023         (GetLabel() returns an empty string in this case
1024         but it doesn't allow the application to distinguish between really cancelling
1025         the edit and
1026         the admittedly rare case when the user wants to rename it to an empty string).
1027     */
1028     bool IsEditCancelled() const;
1029 };
1030
1031
1032 /**
1033     @class wxListItemAttr
1034     @wxheader{listctrl.h}
1035
1036     Represents the attributes (color, font, ...) of a
1037     wxListCtrl wxListItem.
1038
1039     @library{wxbase}
1040     @category{FIXME}
1041
1042     @seealso
1043     @ref overview_wxlistctrloverview "wxListCtrl overview", wxListCtrl, wxListItem
1044 */
1045 class wxListItemAttr
1046 {
1047 public:
1048     //@{
1049     /**
1050         Construct a wxListItemAttr with the specified foreground and
1051         background colors and font.
1052     */
1053     wxListItemAttr();
1054     wxListItemAttr(const wxColour colText,
1055                    const wxColour colBack,
1056                    const wxFont font);
1057     //@}
1058
1059     /**
1060         Returns the currently set background color.
1061     */
1062     const wxColour GetBackgroundColour() const;
1063
1064     /**
1065         Returns the currently set font.
1066     */
1067     const wxFont GetFont() const;
1068
1069     /**
1070         Returns the currently set text color.
1071     */
1072     const wxColour GetTextColour() const;
1073
1074     /**
1075         Returns @true if the currently set background color is valid.
1076     */
1077     bool HasBackgroundColour() const;
1078
1079     /**
1080         Returns @true if the currently set font is valid.
1081     */
1082     bool HasFont() const;
1083
1084     /**
1085         Returns @true if the currently set text color is valid.
1086     */
1087     bool HasTextColour() const;
1088
1089     /**
1090         Sets a new background color.
1091     */
1092     void SetBackgroundColour(const wxColour& colour);
1093
1094     /**
1095         Sets a new font.
1096     */
1097     void SetFont(const wxFont& font);
1098
1099     /**
1100         Sets a new text color.
1101     */
1102     void SetTextColour(const wxColour& colour);
1103 };
1104
1105
1106 /**
1107     @class wxListView
1108     @wxheader{listctrl.h}
1109
1110     This class currently simply presents a simpler to use interface for the
1111     wxListCtrl -- it can be thought of as a @e faade
1112     for that complicated class. Using it is preferable to using
1113     wxListCtrl directly whenever possible because in the
1114     future some ports might implement wxListView but not the full set of wxListCtrl
1115     features.
1116
1117     Other than different interface, this class is identical to wxListCtrl. In
1118     particular, it uses the same events, same window styles and so on.
1119
1120     @library{wxcore}
1121     @category{ctrl}
1122     @appearance{listview.png}
1123
1124     @seealso
1125     wxListView::SetColumnImage
1126 */
1127 class wxListView : public wxListCtrl
1128 {
1129 public:
1130     /**
1131         Resets the column image -- after calling this function, no image will be shown.
1132
1133         @param col
1134             the column to clear image for
1135
1136         @see SetColumnImage()
1137     */
1138     void ClearColumnImage(int col);
1139
1140     /**
1141         Sets focus to the item with the given @e index.
1142     */
1143     void Focus(long index);
1144
1145     /**
1146         Returns the first selected item in a (presumably) multiple selection control.
1147         Together with GetNextSelected() it can be
1148         used to iterate over all selected items in the control.
1149
1150         @returns The first selected item, if any, -1 otherwise.
1151     */
1152     long GetFirstSelected() const;
1153
1154     /**
1155         Returns the currently focused item or -1 if none.
1156
1157         @see IsSelected(), Focus()
1158     */
1159     long GetFocusedItem() const;
1160
1161     /**
1162         Used together with GetFirstSelected() to
1163         iterate over all selected items in the control.
1164
1165         @returns Returns the next selected item or -1 if there are no more of
1166                  them.
1167     */
1168     long GetNextSelected(long item) const;
1169
1170     /**
1171         Returns @true if the item with the given @a index is selected,
1172         @false otherwise.
1173
1174         @see GetFirstSelected(), GetNextSelected()
1175     */
1176     bool IsSelected(long index) const;
1177
1178     /**
1179         Selects or unselects the given item.
1180
1181         @param n
1182             the item to select or unselect
1183         @param on
1184             if @true (default), selects the item, otherwise unselects it
1185
1186         @see wxListCtrl::SetItemState
1187     */
1188     void Select(bool on = true);
1189
1190     /**
1191         Sets the column image for the specified column. To use the column images, the
1192         control must have a valid image list with at least one image.
1193
1194         @param col
1195             the column to set image for
1196         @param image
1197             the index of the column image in the controls image list
1198     */
1199     void SetColumnImage(int col, int image);
1200 };
1201
1202
1203 /**
1204     @class wxListItem
1205     @wxheader{listctrl.h}
1206
1207     This class stores information about a wxListCtrl item or column.
1208
1209     @library{wxbase}
1210     @category{FIXME}
1211 */
1212 class wxListItem : public wxObject
1213 {
1214 public:
1215     /**
1216         Constructor.
1217     */
1218     wxListItem();
1219
1220     /**
1221         Resets the item state to the default.
1222     */
1223     void Clear();
1224
1225     /**
1226         Returns the alignment for this item. Can be one of
1227         wxLIST_FORMAT_LEFT, wxLIST_FORMAT_RIGHT or wxLIST_FORMAT_CENTRE.
1228     */
1229     wxListColumnFormat GetAlign() const;
1230
1231     /**
1232         Returns the background colour for this item.
1233     */
1234     wxColour GetBackgroundColour() const;
1235
1236     /**
1237         Returns the zero-based column; meaningful only in report mode.
1238     */
1239     int GetColumn() const;
1240
1241     /**
1242         Returns client data associated with the control. Please note that
1243         client data is associated with the item and not with subitems.
1244     */
1245     long GetData() const;
1246
1247     /**
1248         Returns the font used to display the item.
1249     */
1250     wxFont GetFont() const;
1251
1252     /**
1253         Returns the zero-based item position.
1254     */
1255     long GetId() const;
1256
1257     /**
1258         Returns the zero-based index of the image
1259         associated with the item into the image list.
1260     */
1261     int GetImage() const;
1262
1263     /**
1264         Returns a bit mask indicating which fields of the structure are valid;
1265         can be any combination of the following values:
1266
1267         wxLIST_MASK_STATE
1268
1269         @b GetState is valid.
1270
1271         wxLIST_MASK_TEXT
1272
1273         @b GetText is valid.
1274
1275         wxLIST_MASK_IMAGE
1276
1277         @b GetImage is valid.
1278
1279         wxLIST_MASK_DATA
1280
1281         @b GetData is valid.
1282
1283         wxLIST_MASK_WIDTH
1284
1285         @b GetWidth is valid.
1286
1287         wxLIST_MASK_FORMAT
1288
1289         @b GetFormat is valid.
1290     */
1291     long GetMask() const;
1292
1293     /**
1294         Returns a bit field representing the state of the item. Can be any
1295         combination of:
1296
1297         wxLIST_STATE_DONTCARE
1298
1299         Don't care what the state is. Win32 only.
1300
1301         wxLIST_STATE_DROPHILITED
1302
1303         The item is highlighted to receive a drop event. Win32 only.
1304
1305         wxLIST_STATE_FOCUSED
1306
1307         The item has the focus.
1308
1309         wxLIST_STATE_SELECTED
1310
1311         The item is selected.
1312
1313         wxLIST_STATE_CUT
1314
1315         The item is in the cut state. Win32 only.
1316     */
1317     long GetState() const;
1318
1319     /**
1320         Returns the label/header text.
1321     */
1322     const wxString GetText() const;
1323
1324     /**
1325         Returns the text colour.
1326     */
1327     wxColour GetTextColour() const;
1328
1329     /**
1330         Meaningful only for column headers in report mode. Returns the column width.
1331     */
1332     int GetWidth() const;
1333
1334     /**
1335         Sets the alignment for the item. See also
1336         GetAlign()
1337     */
1338     void SetAlign(wxListColumnFormat align);
1339
1340     /**
1341         Sets the background colour for the item.
1342     */
1343     void SetBackgroundColour(const wxColour& colBack);
1344
1345     /**
1346         Sets the zero-based column. Meaningful only in report mode.
1347     */
1348     void SetColumn(int col);
1349
1350     //@{
1351     /**
1352         Sets client data for the item. Please note that
1353         client data is associated with the item and not with subitems.
1354     */
1355     void SetData(long data);
1356     void SetData(void* data);
1357     //@}
1358
1359     /**
1360         Sets the font for the item.
1361     */
1362     void SetFont(const wxFont& font);
1363
1364     /**
1365         Sets the zero-based item position.
1366     */
1367     void SetId(long id);
1368
1369     /**
1370         Sets the zero-based index of the image associated with the item
1371         into the image list.
1372     */
1373     void SetImage(int image);
1374
1375     /**
1376         Sets the mask of valid fields. See GetMask().
1377     */
1378     void SetMask(long mask);
1379
1380     /**
1381         Sets the item state flags (note that the valid state flags are influenced
1382         by the value of the state mask, see
1383         wxListItem::SetStateMask).
1384         See GetState() for valid flag
1385         values.
1386     */
1387     void SetState(long state);
1388
1389     /**
1390         Sets the bitmask that is used to determine which of the state flags
1391         are to be set. See also SetState().
1392     */
1393     void SetStateMask(long stateMask);
1394
1395     /**
1396         Sets the text label for the item.
1397     */
1398     void SetText(const wxString& text);
1399
1400     /**
1401         Sets the text colour for the item.
1402     */
1403     void SetTextColour(const wxColour& colText);
1404
1405     /**
1406         Meaningful only for column headers in report mode. Sets the column width.
1407     */
1408     void SetWidth(int width);
1409 };